Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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.

share|improve this question

closed as off-topic by gnat, MichaelT, GlenH7, World Engineer Oct 23 '13 at 14:24

This question appears to be off-topic. The users who voted to close gave this specific reason:

  • "Questions asking us to recommend a tool, library or favorite off-site resource are off-topic for Programmers as they tend to attract opinionated answers and spam. Instead, describe the problem and what has been done so far to solve it." – gnat, MichaelT, GlenH7, World Engineer
If this question can be reworded to fit the rules in the help center, please edit the question.

    
So what's your question? –  MainMa Apr 23 '11 at 2:59
    
@MainMa: Ha, ok i'd edited the last paragraph. Read the first sentence. –  acidzombie24 Apr 23 '11 at 3:12
1  
Not an answer, but related to the question, is this excellent slide deck from CodeConf 2011 about Writing Great Documentation. –  Brandon Tilley Apr 23 '11 at 3:43
    
@Brandon: Thats a good read –  acidzombie24 Apr 23 '11 at 4: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. –  Jarrod Roberson Apr 23 '11 at 5:07

4 Answers 4

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.

share|improve this answer

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.

share|improve this answer

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.

share|improve this answer

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.

share|improve this answer

Not the answer you're looking for? Browse other questions tagged or ask your own question.