Recommendations for Documentation with an Open Source Project?

Question

We are looking at documenting a fledgling open source project, and I was hoping for some suggestions on good methods and or tools that worked well for you. Further, as a developer, do you prefer online docs, wiki based docs, help files, or some other?

Answer 1

While I haven't actually sponsored any open source projects a lot of the work that I do is collaborative. I've found that a wiki with appropriate permissions is an excellent way for people to collaborate on writing common documents. In my case they are typically development stories -- I and the customer work on generating these. I would think that this would work well with collaborative documentation for your project as well.

Answer 2

Sounds like Sandcastle would be a good fit for you.

Answer 3

The all-encompassing way I favor is the use of a Wiki. However, I like the ability of auto-generating docs from source code. There are lots of tools out there but I am especially fond of SandCastle. It provides the same styling as is found on MSDN docs which most .NET developers should already have experience with using and it seems your Open Source project is built in .NET. As far as I can see, the latest framework supported is .NET 2.0.

Answer 4

Seeing as your application is being developed in C#, have a look at Doxygen for generating your API documentation. It is extremely powerful (it does the standard javadoc style member documentation, but will also generate call, inheritance, file dependency and collaboration graphs). Despite its power it's easy to use. It can generate API docs in myriad formats: HTML, Latex, manpage, etc.

For writing manuals, tutorials, and other more flexible types of documentation, seriously consider setting up a wiki. I've used DokuWiki with a great deal of success. It's got support for syntax highlighting, so it's good for code projects. It also has user ACLs which will be handy for an open source project. It also requires only PHP and no database. Of course it offers the standard wiki features like versioning.

Lastly, I should mention trac, which is a wiki, version control, bug tracker hybrid. It's definitely worth a look.

Answer 5

Online docs are always a good idea, especially when Wiki based. They are more searchable, there is some history kept in case of mistakes, and they are generally shorter since they don't have the "sugar" of a long documentation narrative or manual. However, extra care must be taken with article naming and links.

If certain parts of the project code serve as APIs, however, then the relevant knowledge must be captured in the code so it can be visible to those who explore it using the IDE "hover over a call" mechanism. Delocalization of knowledge is a great problem, and people are generally reluctant to do a context switch. If something appears in the function header documentation, it has a higher (though not that high overall) chance of ever being read than if it appears elsewhere.

When writing function header documentation, focus on directives - things that would directly affect the client. These can be imperative (e.g., call X first), or informative (e.g., be aware that X...).

Answer 6

• Doxygen for API/Programmer Documentation
• Docbook XML/SGML for official PDF manuals (with online version available in HTML)
• a Wiki for user created stuff

See how the others do it (Big opensource projects I mean)

But for me apart from the Wiki (mentioned by other posters) some official documentation is always needed for structural/guideline stuff. The wiki is more for knowledge base stuff IMHO

Answer 7

I personally like Sphinx for developer written documentation, partially because of how nice the documentation generated in it looks. It processes documents written in ReST into LaTeX (for printing/PDF) or HTML.

I would not recommend only using a API documentation tool such as doxygen. It's great if that is also used, but it should not be the only form of documentation.

Depending on how active your user community is, I'd also recommend adding a wiki for recipes or other tutorials, its content then can be folded into the ReST documentation used by Sphinx at intervals.