Basically, docs...

[carlsmith]

We don't appear to have any documentation, beyond the FAQ and developer docs in the wiki. I've done some tech writing, and am really getting into Piskel - I even have the kids on it now - so I'd be happy to make a start on some docs for end users.

I'm thinking we should keep things modular (generally one file per feature) and have a tutorial that introduces everything at a high level, that also shows users how to use the rest of the docs to find specifics.

If you can let me know your thoughts on all this, and give me a green light, I'll make a start straight away. The UI changes I've already committed to implementing are all just small things I can tick off as we agree on what to do.

One other thing: Are you ok with using Markdown for this? If so, is there any specific parser or flavour you'd like to use? Performance isn't that big a deal. It's build-time, runs independently of the rest of the build, and we're not working on anything very big. There's CommonMark that seem to be having some success with creating a proper standard, and good old Marked always worked well, but if you prefer something else, that's cool. I'd just really like to use Markdown, if possible.

Edit: As long as we're agreed on what markup language and flavour we're using, there's no urgency on which parser we'll ultimately use to render the files.

[juliandescottes]

Docs would be amazing!

Are you thinking about something that would be hosted on piskelapp.com ? Markdown will be great and I don't have a preference for a specific flavor. I think we can start by writing content.

Later on we can figure out how to publish it and integrate it. One option would be to generate separate HTML pages and then publish them to piskelapp.com. Or we can look at existing solutions such as gitbook.

Do you have some idea on how you would like to split the documentation? I have a few things in mind, but I'd like to hear what you think.

[epicabsol]

It seems to me that it would be useful to have a Tutorials section to show new users how to accomplish goals, and then a Reference section for people who want the details on certain tools or functionality.

Tutorials might include something like Your First Drawing (pen, mirror pen, flood fill, picking colors, undo, layers, etc), Your First Animation (frames, reordering, onion skin, preview FPS), Saving Your Sprite (Naming, saving online, saving to disk, exporting to gif), Advanced Drawing (dither, shading, pipette, palettes), and something to explain the awkward selection/cut/copy/paste/move mechanics.

Reference articles might include all the details on the UI elements in a particular area, and then one article per tool. Screenshots could be useful, keyboard shortcuts would be very helpful.

College limits my time, but I would love to help set up the markdown infrastructure (looks like we could put a Python markdown parser and a tree-style navigational control in the existing piskel-website)

[epicabsol]

I just whipped up a prototype at https://github.com/epicabsol/piskel-website/commit/67a9c59c6c7c02be328392a385cdb00bbcbd19a0 - I haven't used Google App Engine before so there's probably better ways to do things, but it works. The prototype contains a python Markdown library, a controller for rendering markdown, some sample Markdown files and the minimal design needed to get things working. I also think a tree-style page browser would be good to have (think MSDN). Thoughts?

[carlsmith]

Hey guys, sorry I've been away for a few days, and thanks for making a start already.

Are you thinking about something that would be hosted on piskelapp.com ?

Ideally, yes. Integrating them into the website would be perfect.

Markdown will be great and I don't have a preference for a specific flavor. I think we can start by writing content.

No problem. I can use basic, commonplace Markdown inline as I write it, and we can figure out the bigger details as we go along.

Later on we can figure out how to publish it and integrate it. One option would be to generate separate HTML pages and then publish them to piskelapp.com. Or we can look at existing solutions such as gitbook.

I'm easy either way, but I don't think it's going to be too much work to just integrate them into the site directly.

Do you have some idea on how you would like to split the documentation? I have a few things in mind, but I'd like to hear what you think.

I was thinking to do something like what @epicabsol said, but was planning on just having a single tutorial to introduce everything at a really high level, and then modular docs that cover one feature each, for example, the drawing tool or the palette manager. Make each one easy to index correctly, so they are at the top on search engines for stuff like piskel palettes.

@epicabsol might be right about dividing the tutorial up into modules too. Another thing that would be cool to have would be tips, essentially patterns. Some of the things Piskel can do involve a few steps, maybe creating a temporary layer or something. Having mini tutorials , each covering one tip, would work well, and fits into what @epicabsol is saying about having a modular tutorials, like First Drawing and First Animation.

We do want people to be able to find their own way through the docs, only having to worry about animation when they want to animate something for example, but there also needs to be a landing page we can send every new user to that will at least get them comfortable playing around and trying things (which is how most people figure out most things anyway), and aware that they can easily find docs for anything they can't figure out by poking it with a stick.

Dividing the docs into a Tutorials Section and Reference Section makes sense, and I like the names.

I think we're all on roughly the same page here, but would be happy to hear any other ideas??

@epicabsol - I'll look at the prototype soon, probably tomorrow. It's really late here. Thank you for working on it though.

One thought: It would be a bit less costly (not much) to run the Markdown compiler either locally or in the browser, so we're sending everything to the server pre-compiled. On App Engine, this would let us move the docs from the app servers to static servers, which is more efficient, if I understand things correctly. I've worked with Python on App Engine before, but haven't looked through much of the Piskel code yet.

[epicabsol]

As far as markdown compiling goes, we could keep doing it per request like it is in the prototype, or we could compile it all on service startup and hold it all in memory (I like this idea) or we could look into making a script that compiles all the markdown on deploy or something like that. I assume that the current deploy is just copying files, but there might be a way to add a custom build step for running the markdown.

[carlsmith]

The docs will be fairly static content, so there's no need to do any templating or compilation on the server at all. We can compile the Markdown as a build step and put it in a static directory. App Engine can be configured to make certain directories explicitly static. These directories are hosted on servers that are optimised for serving static files. Their content is not available to the code running on the app servers (which are optimised for running code and working with the datastore), but it is less costly to serve.

If working with the SDK requires Python2.7, then a Python2.7 script to compile the docs and update the directory the docs are served from seems like the best approach, but again, I'm not familiar with the Piskel code.

[epicabsol]

Currently pretty much all of the piskel-website pages are templated and evaluated per request, so making the article content explicitly static would prevent the current setup from templating them, requiring generating their entire page HTML ahead of time, and at that point, we might as well use a static site generator and host the docs on GitHub pages.

[carlsmith]

App Engine works well with static content, and has app servers when they're needed, so moving to Pages would just limit what we're able to do in future.

If we're currently generating each page on each request (and it's not being auto-cached by ndb or whatever), then we should open an issue to fix that. It's not a problem while the site is relatively small, as Google is paying for everything, but once the site takes off, App Engine gets very expensive very quickly if you don't have everything implemented optimally.

App Engine developers tend to use the simplest approach to get things up and running, as efficiency is a non-issue at first (this is one of the cool things about the platform), but once your site starts to gather momentum, you really need to go back and optimise everything (in terms of billing, not actual efficiency, which never matters to us).

Ultimately, none of this matters very much right now. I'll get on with writing the docs (which I started on yesterday), and you can implement the server whichever way you think is best for now. If we need to redesign stuff later, we can worry about that then. It's easily changed.

[juliandescottes]

The templating is useful to keep the navigation header (which is dynamic with links to the current user's gallery etc...). But I guess it's not critical to keep it for the documentation pages, so they could be fully static.

I like the idea of having the docs as a separate project from the current piskel-website for three reasons. It could be GH pages or a second app-engine project. It might remain in the free appengine quota.

First, my appengine code is super messy and this would just add complexity to it. Second, deploying the docs would not depend on me updating appengine. I imagine we want to update docs more frequently than I usually update piskelapp.com. I could also give you publish rights for the docs. Third, piskelapp.com currently has between 2 and 3 million pageviews/month. I'm regularly tweaking it to reduce costs, but it still ends up burning ~150$/month. I'm not really expecting static docs to be crazy expensive, but keeping the billing separated would also be nice.

As you said we can also figure that as we go!

[carlsmith]

I didn't realise the site had so much traffic. Nice!

We don't strictly need templating to customise the header. The plan was to serve the same client to every user, and have a JSON API for everything else. The app would fire up and immediately use the API to get the user's information, then update the UI. However, on reflection, I don't think this would save us any money, as the connection request would be as costly as the one that currently templates the page, and we still need to serve the page. The server would be client agnostic, but without mobile clients to use the API, that's totally pointless.

Sorry (to @epicabsol too) for creating confusion around this issue. I was trying to get ahead of those costs, but hadn't thought it all through properly.

Putting the docs on GitHub Pages might be the best idea, just to avoid having to pay for them later. The docs will presumably be as permissively licensed as the software??

I've made a start on the docs, and will have something to share soon.

Again, sorry @epicabsol. I should have read the code and properly considered everything before weighing in.

[carlsmith]

Just an idea: I have an unmaintained CoffeeScript shell on GitHub that's a pure clientside app, except users are able to publish little Web scripts (a bit like CodePen pens) that need storing. The app is hosted on GitHub Pages, and uses gists to store the users' scripts.

The GitHub API is pretty powerful. It should be possible to host the Piskel site and editor on GitHub Pages, and use gists to store users' sprites. Users would need a GitHub account to use it, but the editor would still have all the features it has now.

We could put the docs on there too obviously, and just focus on GitHub. I like App Engine, but am just thinking of ways to avoid incurring rising costs as Piskel becomes more popular.

[carlsmith]

Status Update: The docs are coming along well. I did some more this evening. Now, my kid has me up late with a cough, so thought I'd check in.

As I'm working on things, I'm warming to the idea of publishing the docs as a little ebook, like the Git Book. It would be easy to read online, but presented as a little book you can read on a phone or ebook reader too, manually typeset with some nice pixel art.

The following TOC covers what it would likely have out the gate, but we could develop it over time to create a neat little textbook for people new to pixel art and sprite animation that uses and fully documents Piskel. This is all just pipe dreams at this stage, but to put the idea out there...

Chapter 0: About This Book

A few sentences explaining what the book is, what it contains and how it's structured, followed by a detailed table of contents, something like this one, but more fleshed out.

Chapter 1: Introducing Piskel

A tutorial offering a very high-level overview of the editor and the services at piskelapp.com.

Chapter 2: Drawing & Painting

A short tutorial introducing pixel art in the context of Piskel.

Chapter 3: Sprite Animation

A short tutorial introducing sprite animation in the context of Piskel.

Chapter 4: The Complete Reference

This chapter will be a fairly dry, but fully detailed reference, listing every feature, structured like API docs, but more fun and user friendly.

Appendix A: Exporting Your Work

A short document explaining the options for exporting sprites from Piskel to use with other software.

Appendix B: Copyright & Licensing

A plain English explanation of the license (pointing out that it does not apply to users' artwork) and a promise not to change the license at a later date.

I'm really just thinking out loud with all this, but so long as we still end up with something that is nice to read online and indexed by Google, an ebook style book format might work.

[RangerOri]

Hey, maybe instead of a PDF file, you can create a website with the documentation. I saw this tool: https://docsify.js.org/#/quickstart https://github.com/QingWei-Li/docsify-cli Which has created a documentation website just from the README.md file. I am looking for some other auto-generation tools that will create a doc from the code, since I'm trying to learn it, and it's not easy to understand. If I had some UML generator, it would've been easier.

I also saw this tool, however, I haven't checked it: https://github.com/dauxio/daux.io

[juliandescottes]

Thanks for the update @carlsmith !

How are you writing the docs for now? Are you writing separate MD files? Are you using some kind of structure to get a TOC?

I think it is a good time to create a separate repository which would automatically be published to GitHub pages. This way we could start publishing bits of documentation as we go, rather than waiting to finish all the docs before figuring out how to publish them :)

I'll try to setup a basic repo based on something we used at work and we can iterate there. If you have some kind of structure/tooling you're already using, let me know!

The docs will presumably be as permissively licensed as the software??

Yes, I think they should!

Hey, maybe instead of a PDF file, you can create a website with the documentation.

Thanks for the suggestions @RangerOri, I'll take a look at them! I think we all agree online docs are a must-have, the ebook is a nice plus on the side :)

[epicabsol]

I have used the 'hugo' static site generator ( https://gohugo.io/ ) successfully in the past (my project is hosted on GitLab Pages at http://frostysuite.us.to/ ), so that's an option.

[carlsmith]

Hey guys. Thanks for the support with this. It's much appreciated.

I'm only using basic Markdown syntax (which was made for this type of thing), so it could be rendered by any parser. There's no metadata or anything parser specific at this stage.

I'm happy to structure the content however we agree is best, for whatever tools people want to use. @juliandescottes may need to make the final call on that, as there seems to be a range of opinions.

The approach I'm taking for now is to just keep everything super simple. The directory structure would end up looking roughly like this

• root
  • images
    • logo.png
    • favicon.png
    • screenshot.png
  • tutorials
    • introduction.md
    • painting.md
    • animation.md
  • reference
    • pen_tool.md
    • line_tool.md
    • animation_preview.md
    • keybindings.md

The tutorials and reference directories only hold MD files, which link to one another and to the images in the images directory. The links would be absolute links, but relative to the root directory, for example:

• /images/screenshot.png
• /reference/pen_tool.md

I personally think this is the best approach, if we want to be free to use the content however we like later. Rather than structure everything according to the requirements of a specific framework, and end up tied to that tool, I'd rather just have a simple directory structure, with simple, explicit links, and then do the rendering ourselves. We should keep in mind that we're not creating anything very complicated - a few tutorials and a reference. There will likely be quite a lot of files in the reference, but they will generally be a few paragraphs each. The tutorials will be longer, but there will only be a few of them, maybe growing to five or six, long term, optimistically.

With a good Markdown library, I'm confident we can easily create our own script that could generate a static website. We could also write scripts for generating ebooks, PDFs, Rich Text files or anything else we liked (using the explicit links in the hypertext to generate whatever the output format uses to link content and so on).

I agree that having these docs online as a conventional (mobile friendly) website (that is indexed by Google) is the primary objective here. Any other format would be secondary to the website.

Again, I'm happy to hash this all out with everyone else, and then write the content the way that works best for the Piskel project. I'd just personally prefer to keep it simple, and write our own scripts that only depend on a good MD parser.

I'll put these up in a repo really soon, I promise. I just want to get something half decent together first. I don't want to publish them yet though, as at first, we'll basically just have an introductory tutorial that is really high level, that links to tons of the little docs in the Reference for more detail, but those links will mostly be dead at first. I don't mind getting it all up online so people can see it to help improve it, but don't think we should publish it proper, until it's in a working state.

Maybe we can pull some stuff out into its own second repo and abridge it during the interim, so we can publish some stuff earlier, but it's not obvious how at this stage. We'll see.

One thing I need some help with is just naming things in the UI. I'm currently using terms like the Animation Preview and the Viewport, but don't want to invent my own vocabulary and force it onto everyone else. I'll get the tutorial drafted and online, and we can go over the terminology and fix it then.

Again, thanks for the support everyone. I will have something to show really soon.

[juliandescottes]

Sounds good to me! I suggested creating the repo + automating publishing right away because I felt it could be less stressful for you. But if you're comfortable working on this on your own at the moment that's fine for me :)

[carlsmith]

Just at this stage, while we're still figuring out exactly what needs doing. We can easily move things around once we're further along.

I'll put everything online soon, so everyone can see where we are, and we'll go from there.

[epicabsol]

I have a basic Hugo site working, but I'm at a crossroads. I'm not sure whether we want to:

1. Copy the HTML and CSS directly from the existing piskel-website, and try to make both sites feel like one site, transparently linking people across
2. Start clean maybe just based on bootstrap and style the site similar to piskel-website but without making them appear as one
3. Copy the HTML and CSS directly from the existing piskel-website, and adapt the layout to our needs to be similar but not absolutely identical
4. Start clean with maybe just nothing / bootstrap and go for a vaguely similar style?

So I guess these are two orthogonal issues,

• copy existing CSS and most of the HTML or imitate anew based on something like bootstrap
• design exactly like existing piskel-website or similar visual style, but uniquely for docs)

I personally prefer rebuilding in a similar visual style (both because I'm used to how bootstrap does things, and because some of the existing site layout might not make sense for a purely docs site), but @juliandescottes is probably the one with the most insight for this decision.

[carlsmith]

I'm a fan of the current look and feel at piskelapp.com, and the dark grey and gold theme. That said, reading white text on a dark grey background might not be a good choice for longer docs. It should definitely look consistent with the site, but we probably want the docs rendered with dark text on a white background.

[juliandescottes]

I have a basic Hugo site working, but I'm at a crossroads.

Thanks for raising those points!

I think we should treat the docs project as a completely separate project and simply aim for consistency with piskelapp's theme. I don't want us to try and reuse CSS or markup from piskel-website.

I think that corresponds to option 4 @epicabsol ?

reading white text on a dark grey background might not be a good choice for longer docs

Good point. However most e-readers propose both dark and light themes, so I don't think docs on a dark background are necessarily a dead-end. It might be difficult to make the docs look consistent with the site otherwise?

[carlsmith]

On the light/dark theme thing, I was just looking at the homepage, where we have a subtle chequered pattern at the top, just below the banner. It's all made from greys that are roughly #555, which isn't super dark.

If you've ever used Apple's Mail app, they use a style there that you'll have seen used in other places as well. The basic approach is to present all of the content in nicely typeset divs that have white backgrounds, fine grey borders and drop-shadows, so they look like sheets of paper floating in the air. The background is normally grey and fills the viewport.

There's a simple example here, but we'd turn each section into its own 'sheet of paper', so longer docs, like tutorials, would have a bunch of them with gaps in between. That would look especially nice, as the 'sheets' will always be exactly the right size for their content.

We could use the colour scheme from the homepage to create a background, and have floating sheets of white paper for the content.

An alternative approach is to just provide a switch for users to pick between light and dark themes, but it might be overkill.

[carlsmith]

I'm sorry for the delay with this. I've done some of it, but haven't been able to work on it for a while, and am mindful that people were depending on me. I don't want to make excuses. I hope to get back into it before long, but don't want to make another promise that I don't keep.

Again, I'm sorry. I hope to be back soon.