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 two are independent.

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:

• BiNGO

• WikiPathways App

• Enrichment Map

FAQs

User manual

A few examples of User Manuals for Cytoscape apps:

• ANIMO User Manual

• EnrichmentMap User Guide

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:

• EnrichmentMap App "report-a-bug" instructions

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