Thursday, June 25, 2015

A generic screenshot webservice for documentation

@mathias.schreiber gave me some great feeback on Slack about the tools I want to build as part of my T3A budget (see my most recent blog post):
we plan to move this away from rst anyways, thus I ask myself how we benefit from the toolset
He also clarified that he's only talking about finding a tool that's easier to use, like Confluence, and it would only be for the manuals, not the reference documentation. And, he also tried to make it very clear that they aren't changing document formats right now, and there hasn't even been any official conversations in the ML. There are only plans, so far.

I'm really glad he pointed out this possibility on the horizon. Now, I need to generalize any tools I make so that they can be used by Confluence, Sphinx, or (almost) any other documentation tool that serves the needs of the project. Knowing it is on the horizon, I can design the tools to work in that context.

Here's my first stab at generalizing the screenshot tools.

Instead of starting with screenshot generation, I'm going to start with a simple web service that allows some kind of input (just an image id for the MVP, and later, it will accept a full behat scenario to describe the image that should be generated) and return a final image URI. (initially the image will serve up some placeholder/transparent image that is set to expire very quickly, and later the placeholder can be replaced with the generated image) This way, frequently regenerating screenshots in user manuals will not cause the git repo to bloat significantly. This will allow us to put the images directly in some kind of CDN service (an actual CDN if needed, or something like Dropbox or maybe Google Drive).

For the first MVP of this web service (which will only be accessible to a clients that are whitelisted, such as build.docs.typo3.org.), I will still manually generate any screenshots/screencasts. In the next phase, I will integrate behat (or something similar) that can describe the screenshots that should be generated. I'll add the ability to annotate screenshots later on.

This way, a description of the necessary screenshots can be embedded in manuals without requiring the document author to generate the screenshot (thus breaking the flow of writing the document). Then that description gets sent to the web service where something (or someone) takes the description and generates the required screenshot and makes it available at the URI provided by the web service. Even without automating the screenshot, this will allow the author, or other contributors, to go through the queue and generate all of the needed screenshots with the annotations.
This service would then need a sphinx plugin, or a wikimedia plugin, or a confluence plugin, or whatever tool is used to write manuals.

So, my budget can be useful to both TYPO3 and Neos, even if one or both teams decides to move the user manuals away from restructured text format.