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 (Tutorials, FAQs and User Manual) are listed in a suggested order of priority, starting with user tutorials. The last two are independent. A simple website provides the best platform for promoting and documenting your App, here's an example: CyTargetLinker website.
In addition, the Cytoscape App Store page for your app can serve as a central point for organizing documentation. You can use it to link directly to publications, contact emails and code repositories, but for tutorials/faqs/manuals you would still need to link to an external webpages. The App Store page can also include some brief instructions for installation and usage in the body of the page.
More about how to add this information to the App Store can be found in the Submit Your App to the App Store step.
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:
- An introductory description of the app and the use case covered in the tutorial.
- Any data necessary should be provided in the tutorial for download.
- Step-by-step instructions. For an introductory tutorial, assume that the user has never seen or used the interface.
- Screenshots of the app for each step, to highlight specific features used.
A few examples of effective tutorials for Cytoscape apps:
FAQs
The format of Frequently Asked Questions is a great way to allow for quick access to instructions for specific topics or issues. For example, if there are known issues with your app, a FAQ is the most appropriate way to communicate solutions to users.
Here's an example of a FAQ section on a website for a Cytoscape App: AllegroMCODE FAQs.
User Manual
A few examples of User Manuals for Cytoscape apps:
Bug Tracker / Developer Contact Info
A simple bug tracker is very useful for both developers and for users. For example, GitHub (and other code repository hosting services) includes an issue tracker, but there are also specialized bug tracker tools like BugZilla.
Include clear pointers to where and how to report bugs on your website. Here's an example:
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