[chimera-dev] how to write documentation for an extension

[Elaine Meng]

Hi Jan,
We do strive for a reasonable amount of consistency in the documentation that we ship, but there is no official guideline at this point.  We only have something like that for the extension’s GUI text:
<http://www.rbvi.ucsf.edu/chimera/docs/ProgrammersGuide/frameguidelines.html>

One reason is that the tools themselves vary considerably in complexity and organization, calling for variations on the basic documentation format.

My advice would be to start with the HTML manpage from the most similar existing tool (click Help button, use browser to save HTML, then modify, at least if you are comfortable directly text-editing HTML).  If you are not comfortable working with HTML directly there are probably other  routes to ultimately generating HTML with a similar organization and style. 

We don’t mandate anything specific, however, and the mere fact that you are actually thinking about documentation is a positive!  Of the various extensions distributed by others, some have little documentation, some are documented on websites, and some have non-HTML documentation (PDF, etc.).  My general impression is that most don’t include documentation in their download.
<http://www.rbvi.ucsf.edu/chimera/plugins/plugins.html>

Thanks for asking!
Elaine
-----
Elaine C. Meng, Ph.D.                       
UCSF Computer Graphics Lab (Chimera team) and Babbitt Lab
Department of Pharmaceutical Chemistry
University of California, San Francisco

On Jul 25, 2014, at 6:16 AM, Jan Kosinski <kosinski at embl.de> wrote:

> Hi,
> I wrote a custom extension and now I want to create a documentation page that upon clicking a Help button opens a web page similarly to some other Chimera tools.
> Is there any html template, style guide or any important instructions I should follow for implementing it?
> Thanks in advance,
> Jan