Collaborations Workshop 2019 (CW19) #CollabW19 2019-04-01 to 2019-04-03
Maintainable Tutorials Made Quickly - HP16-CW2CC
Hackday Idea Proposer
Adam Jackson - magicguy@gmail.com
Context / Research Domain
This tool assists documentation of small command-line programs as created by novices
Problem
Many researchers have a limited time/energy allocation for their software development. Documentation tends to be a low priority, and within the documentation tutorial/how-to content is somewhat intimidating. This is a problem as this content is especially important for bringing in additional users, who may be able to contribute experience (and code!) to help the project develop.
Some specific challenges for tutorial and how-to documentation are
- Creating an attractive and communicative layout
- Accurately capturing inputs/outputs
- Keeping the tutorial content up-to-date with API changes
Solution
A tool to quickly create a tutorial/how-to page as automatically as possible.
- This is a template which can be annotated with additional commentary
- This should be able to somehow integrate with a shell session to capture the input commands and outputs; in addition it should be easy to flag generated files and screenshots as belonging to a particular step.
- The generated page is rich with styling/javascript functionality to fold/unfold levels of detail and extracted information
- A program is generated/supplied which can be added to a test suite. This executes the tutorial code blocks and verifies the output if possible. This will flag errors and provide a level of confidence that the tutorials remain up-to-date.
Diagrams / Illustrations
You can include diagrams in this section. Please ensure you have the right to use the image(s), and include an attribution if applicable.