Cytoscape Wiki
Prepare Documentation
Overview
Your app is ready for use! Now you need documentation. Effective user documentation is crucial for making your app accessible and useful to users. This step will outline some useful types of documentation and point to some examples.
Process
The first three of the below documentation resources are listed in a suggested order of priority, starting with user tutorials. The last three are independent. The most important type of documentation to prepare is tutorial-style instructions for basic use.
User tutorials
Good user tutorials are crucial for users to be able to use your app. User tutorials should be written in the style of a workflow, describing the most common basic use cases, with additional and advanced use cases formatted as separate tutorials. A good tutorial should include:
- A clear description of the use case covered
- Supply any necessary data as downloads
- Include step-by-step instructions. For an introductory tutorial, assume that the user has never seen or used the interface.
- Include screenshots of the app for each step, to highlight specific features used.
Examples of User Tutorials
Below is a list of a few effective tutorials for Cytoscape apps.
FAQs
User manual
Examples of User Manuals
Bug tracker / developer contact info
A simple bug tracker is very useful for developers and for users. For example, GitHub includes an issue tracker, but there are also specialized bug tracker tools like RedMine. [ref]
In addition to information on how to report bugs, it is also important to include contact information for the development team, like an email for the lead developer or outreach coordinator, or a mailing list for the developer group.
Technical documentation
Technical documentation is useful for other app developers and the larger scientific community in general. Consider including:
- Detailed write-ups of algorithms and methods used. Links to published papers are recommended.
- Link to code repository, such as github