2

Different from Fastest way to document software architecture and design. I'd like to write a manual for my software which includes

  1. Command line usage
  2. Howtos/Tutorials on using the software
  3. Example code for writing plugins
  4. Manual on functions and classes for the plugin sdk

I'd like to mark words for linking so i can write "also see FuncA, FuncB, etc" with each func as a link. Perhaps have the code sample monospace width/font and indented like you would see in many books.

What software/markup/format may i use to generate a manual? I'm unsure what format the manual will be but it will likely be html, pdf or both. Bonus if its a text format and plays nicely with source control (i'm using git) but that doesn't matter as i'll probably have it outside of my source control.

Community
  • 1
  • So what's your question? – Arseni Mourzenko Apr 23 '11 at 02:59
  • @MainMa: Ha, ok i'd edited the last paragraph. Read the first sentence. –  Apr 23 '11 at 03:12
  • 1
    Not an answer, but related to the question, is this [excellent slide deck from CodeConf 2011 about Writing Great Documentation](http://www.slideshare.net/jacobian/writing-great-documentation-codeconf-2011). – Michelle Tilley Apr 23 '11 at 03:43
  • @Brandon: Thats a good read –  Apr 23 '11 at 04:34
  • 1
    @Brandon that is a terrible slide deck, full of FUD, un-substantiated opinion and and dogma. 20 years of experience in the software industry tells me developers are the worst people to write documentation, and other studies say the same thing. –  Apr 23 '11 at 05:07
  • @Jarrod: I agree to BUT i liked it because it told me about sphinx and readthedocs.org. It also helped that i didnt think much about the content and knew i am forced to write this doc (i am the only one who knows the system) -edit- also it didnt give a single reason why i should do anything. Which i thought was bad but didnt care –  Apr 23 '11 at 05:54
  • @Jarrod: The talk was approached from the perspective of a library, etc. I agree devs shouldn't write the documentation for your software company's flagship product, but I disagree that they shouldn't for documentation *of code*. – Michelle Tilley Apr 23 '11 at 06:05

4 Answers4

2

One word:Doxygen. It fits into all your needs. You can use to output to generate plain HTM , or create a CHM file or latex output and many more. It automatically links class names in the text. For method names you just have to add the @see or @ref. It is very simple to learn and shouldnt take you more than 2-3 hours to get familiar with the basic tags. It will warn you if parameters are missing or incorrect. You can easily add a CSS file that will generate the look for documentation. And you can doucment it witin the code itself so you dont have to worry about keeping two different sets of files.

One feature I really loved is the ability to integrate graphviz to automatically generate UML collaboration diagrams. Do try this once. Best of all it is totally free.

DPD
  • 3,527
  • 2
  • 16
  • 22
0

Lots of modern languages have associated standards for generating documentation for their code (ex. javadoc and pydoc). These allow you to use structured comments in your code to generate external documentation for the code. Doxygen is an example that is not specific to a given language.

As for the user manual parts that are not directly tied to an api, you might have to look a little further. I would guess that those tools might provide functionality beyond documenting the code structure. However, for a project I'm working on, we ended up using JavaHelp to provide context sensitive links to our user manual. JavaHelp ends up just being a directory of basic html files for each page and a few xml files to define the hierarchy and context sensitive links.

unholysampler
  • 7,813
  • 1
  • 30
  • 38
0

A Wiki is the best way to document all the things you mention. We use MoinMoin, with its rich plug in system you can manage a live living corpus of knowledge easily and deliver in just about any format you desire. If you can get your content into DocBook you can convert it to any other binary deliver format you desire.

0

I am a java architect and use Omondo EclipseUML to provide documentations.

How it works:

It is pretty easy because first I reverse the full project by using the reverse engineering feature.

I then also reverse the other jar files that are used by the application. It means that I show where are the calls to the other frameworks. It means that I can mix Framework jar file having .class code with my project having .java code. See more at : http://www.ejb3.org/jar_file_reverse/jar_file_reverse.html

I have now one large model composed by my code and multiple frameworks which have been merged. Each one is a small model part of my single model. All my model information is therefore merged together but it is still very readable.

Finally I create class diagrams views from my model by drag and drop and add my own comments. Each diagram explain a concept and an architecture specific part. I usually create about 100 diagrams for a large project. I think that developers don''t need more than 3 hours to start codding inside an exiting code and add the needed code at the right place without breaking the existing architecture.

Developers keep my diagrams as visual documentation and I think that they compare it to the java doc. All my diagrams once created are only model and not anymore related to the code. It means that once the code has been documented by UML diagrams we can decide either to keep it in synchrony or not. I prefer to separate them and at each iteration to merge my code one more time.

UML_GURU
  • 258
  • 2
  • 3