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.

appstorelinkout.png

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:

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:

Cytoscape_3/AppDeveloper/Cytoscape_App_Ladder/Prepare_App_Documentation (last edited 2015-01-30 23:52:54 by AlexPico)

MoinMoin Appliance - Powered by TurnKey Linux