Documentation & Documentation Tools for Neos/Flow

Added by Naike Beggiato about 3 years ago

This budget will cover some of the work that needs to be done to get Neos/Flow documentation up to date. This includes: (1) Write missing Neos/Flow manuals and manual chapters; (2) Significantly revise the Neos and Flow documentation; (3) Infrastructure/Tools to make it easier for people to contribute to documentation with the Flow/Neos projects; (4) For the Neos Editor's Guide: Create an system to automate creation of screenshots and short videos of how to use Neos. The last item will probably use phantomjs, ffmpeg and possibly behat to generate the screenshots/videos.

Budget Leaders for Docs Team (Fabien) and Neos/Flow Team (Karsten) budgets are aware of this budget application. This application covers some tasks that are not part of either of those budgets. This application does not include developing any features for Neos/Flow, nor does it cover infrastructure on docs.typo3.org. The ultimate goal is to make the Neos/Flow manuals more complete and useful, as well as easier to keep up to date.

Budget Owner: Jacob Floyd
Budget Amount: 13'750.00 Euro


Replies (5)

RE: Documentation & Documentation Tools for Neos/Flow - Added by Marcus Schwemer about 3 years ago

Hi,

why should the T3A and it's members pay for documentation? Working time should be only payed in very rare cases. This budget includes only working time and no enabling and other costs.

Best regards
Marcus

RE: Documentation & Documentation Tools for Neos/Flow - Added by Jochen Weiland about 3 years ago

In my opinion there is no need to create tools for automating screenshots and capturing short videos. There are good tools like Snag-it and Camtasia readily available that make such tasks easy and straight forward. Using such tools would also speed up the update of the documentation, since nobody needs to wait for these tools to be created.

Best regards
Jochen

RE: Documentation & Documentation Tools for Neos/Flow - Added by Michael Stucki about 3 years ago

Jacob & Jochen: How many licenses of such a tool would be needed, and how much do these products cost? Thanks for your feedback!

RE: Documentation & Documentation Tools for Neos/Flow - Added by Jacob Floyd about 3 years ago

@Marcus
This isn't really enough time to actually complete these things. It's more like an "enabling" cost in providing just enough for me to spend at least 5 hours a week throughout the year. If there is money to cover some minimum costs, then I can probably spend more 'time' than this is paying for.

@Jochen
The tools to make a screenshot, and the tools to automate the creation of a screenshot are very different. Actually making the screenshot will be delegated to existing tools, which, as you point out, are excellent.

Taking screenshots and screencasts, though simple, take significant amounts of time. I'm writing an editor manual for Neos that uses extensive screenshots and short (<10 second with no sound) animated demonstrations of how to do practically everything in Neos. To create screenshots with that kind of detail--adding the numbered annotations on top of the image where necessary or demonstrating a short process described in the text of the documentation--would be a significant time hog. Since we need more documentation, that would mean that the Neos editor manual would quickly become the MTB (modern template building) tutorial1 that we know and love for TYPO3 CMS. How many years did it take for someone to update the screenshots in there? It's not a matter of having good or simple tools to take the screenshot, it's a matter of actually sitting down regularly and going through the repetitively tedious (albeit simple) process of redoing the screenshots so that they do not show out of date things that might confuse editors.

What is the opportunity cost of manually taking screenshots? If someone must manually make screenshots, then (A) the manuals will include fewer screenshots to avoid the maintenance burden that having many screenshots would cost, (B) the time spent making screenshots cannot be spent improving the rest of the documentation, or working on some other feature. It is simple when you have one or two, but I would like to regenerate the screenshots as part of the documentation build process.

Automating it serves three purposes:
(1) Keep the guide/manual up-to-date with recent screenshots that match the current version of Neos
(2) Serve as a warning sign that the guide/manual needs to be updated. When an error occurs in creating a screenshot, the guide/manual will have to get updated before the next version gets released. This matches up with the Neos/Flow team's release cycle which specifically includes documentation.[2]
(3) Allow more people to contribute to documentation, including adding the relevant screenshots, without getting the tools (and potentially licenses for the tools) necessary to make those screenshots.
(Bonus) Keep the screenshots consistent stylistically throughout the manual (eg the numbers or highlighting different sections on the images).

The different components of automating screen capture already exist. Behat can already use PhantomJS to grab screenshots to test for visual changes between versions. We already have an open source account with Sauce Labs which could help with screen capture in different devices or browsers (if/when we end up needing that). Someone else has already figured out how to automate creating short animations/videos using phantomjs3. So, the tools are already there. I'm proposing to hook those existing (no cost) tools into the documentation build process so that the screenshots can be generated when the docs get built.

[1] http://docs.typo3.org/typo3cms/extensions/doc_tut_templselect/ModernTemplateBuildingPart1(mtb1)/TheBasics/CreatingAPageStructure/Index.html
(Hint: the last time the MTB was updated was 2003)
[2] http://neos.typo3.org/contribute/all-about-releases.html
[3] http://mindthecode.com/recording-a-website-with-phantomjs-and-ffmpeg/

RE: Documentation & Documentation Tools for Neos/Flow - Added by Jacob Floyd about 3 years ago

Michael Stucki wrote:

Jacob & Jochen: How many licenses of such a tool would be needed, and how much do these products cost? Thanks for your feedback!

In the last paragraph of my lengthy response, I parenthetically responded to your question:

the tools are already there. I'm proposing to hook those existing (no cost) tools into the documentation build process

I doubt I'll need any tool that requires a purchased license. The open source tools in this area are more than enough for what we need.

    (1-5/5)