What format is your documentation in?

Question

I am going to be writing documentation for two web services that I developed, and I started wondering what people on here do for documentation.

Do you create it in an HTML file so it can be viewed in the browser? Word document? Wiki? What do you guys/gals use?

I was originally leaning towards creating an HTML page since it seems a little more open and friendly than a word document. Plus I can use the prettify javascript to make code samples look nice. Our company has a Sharepoint though, so an HTML file may not be the best choice given that most documentation is put up in spreadsheets and word documents.

Answer 1

There is no right or wrong answer. I've seen many projects done effectively with both Word (or the equivalent) and online/html/wiki. I've also seen many projects fail under both types of documentation technologies.

Bottom line: it's up to you and your team as to which is the most effective way to communicate, but if you don't communicate, you're going to fail.

Answer 2

Wikis are a very easy way to get started IMO; if you have a technology available already, why not go for it. Really depends on what you are comfortable working with.

Related/duplicate questions with good results and a lot of inspiration:

• Minimalistic tools for developer documentation

• Good documentation software

• What tool or technology does Apple use to create its documentation?

Answer 3

There are a lot of document generation programs that will create documentation for you from source code, I believe they generally output xml, and can transform that into html for you. IMO HTML is the way to go as it is the most cross platform/browser format. Sharepoint has no problem storing HTML documents.

Answer 4

The biggest problem I see with Word (or other binary data) documentation is versioning. If you keep your documentation under version control (CVS, Subversion, ...) you do not get proper diffs unless you stick to text formats (HTML, DocBook, ...).

I would recomend DocBook as the source for the documentation. From DocBook you can generate all sorts of neat output formats (HTML, PDF, ...) if you want to distribute the documentation.

Answer 5

I use the doxygen tool to generate documentation from the standard C# xml comments. I then write introductory text and extra pages in the doxygen format and place it in one or more simple text files that I include in the doxygen build.

Answer 6

I use Sandcastle, and the Sandcastle Helpfile Builder. I author the doc in .aml files, then generate from that a .chm or a set of .htm files.

Think of it as a project system for documentation.

Example HTML output.

Answer 7

The best solution I've found is to use pod format, which can then be easily transformed into text, html, pdf, man, hlp, or just about any other format you can think of by freely available tools. It was originally created for perl documentation but is quite usable for any project, even if it has nothing to do with perl

Answer 8

Using an automatic mechanism such as Javadoc or Doxygen has the advantage that documetation stays in line with the code. But in my opinition it can lead to documentation that is good in detail but lacking overview.

Answer 9

We are using fogbugz wiki. With some plugins for latex and graphs, it is rather pleasant to work with. Every document has a nice Wxxx number, which can be referred to as an ID of a convention or a meeting. All information can be linkified, every investigation report linking to cases, every design linking to revisions in source control, etc - very comfortable.

Subscriptions are very useful. This way, anybody can change anything, and the document's owner will review the fix. Another important feature is search: with more than 2000 documents, there's one place to find things in. If you don't find, you will find something related which will point to your document as "See also".

Answer 10

XML, which is what DocBook is, essentially. XML works everywhere on any platform with any programming language, can be transformed into anything, and is human readable.