The Pain
I’ve been writing docs for the Neos project, watching for ways to make it easier for more people to get involved. The Neos Editor Guide (a user manual I’m writing) really needs a lot of screenshots to be effective for the end-users that need it. But, creating docs with visuals is annoying at best, even for a technical writer like me. Screenshots are annoying to produce, and keeping them up-to-date is painful. I want to create something to make this part of documentation easier to produce and maintain.As you write the docs, you need to create screenshots. You could interrupt the flow of writing to go create the screenshot, and then struggle to get back into the flow of writing. Or, you could try and make notes on what screenshots are needed and deal with making them later. Hopefully, you won't miss any of the image placeholders in the docs. Whichever workflow you choose, switching contexts like that causes a lot of mental friction. Taking screenshots is annoying. Plus, it’s hard to get someone else to create the screenshots for you because they have to have both sets of tools as well.
And then, someone’s got to maintain the docs. How many times have you seen manuals where the screenshots are 5 or 10 years old? Once you write a doc with lots of screenshots, no one will ever update it; If someone does update it, they won’t update the screenshots. Screenshot maintenance is tedious, so no one does it.
The Seed of an Idea
What if we automated screenshots? There are a variety of tools that we could use to do this, including Behat, Cucumber, phantomjs, ffmpeg, etc. Then, you could describe the required screenshot in the doc you are writing and let Sphinx call the other tools to generate the screenshots. However, automating image creation will create a lot of images. If you keep your docs in a git repository, like I do, your git repository will quickly bloat with all those images; that kind of bloat makes git fetches slower and makes turns the git experience into an annoyance.So, what if all of those screenshots were stored in some external service like Dropbox or Google Drive, or some other CDN(-like) service? Then, Sphinx (or whatever doc generator you use) would need a way to get the URI of those images without hard-coding them in the docs.
A Solution
So, I'm building a web-service for documentation visuals like screenshots. The service will take an image description (sent by Sphinx or some other doc generator like Jekyll, WikiMedia, or Confluence), and return an image URI. In the background it can let users upload the screenshots or automatically create them with something like Behat. Let's say goodbye to user manuals with screenshots that are out-of-date.While writing the docs, the author just includes a description of the screenshot. Then, as far as the author is concerned, the description of the screenshot gets replaced with an actual screenshot. No more context switching between writing and taking screenshots. Someone else or some other program can deal with actually taking the screenshots.
Imagine a website like crowdin where people upload screenshots instead of localizations. The website would list the screenshot descriptions and let users upload a screenshot for each one. Automate what we can, and leave the rest to volunteers. That gives more people a way to contribute to the docs.
