|
Well, developers aren't great at writing documentation but we have to. What platform do you use to write it? Microsft Word? Open Office? Latex? Please note, I'm looking for something that is (a) cross platform (should work on at least Linux and Windows) (b) easy to use for developers and non-developers (c) and if possible version controlled |
|||||
|
|
Most of our internal documentation is on a wiki but our external documentation is done in DocBook format. The main advantage of DocBook for us is it's XML which makes it far more suitable to managing through a version management system, identifying changes and so on. The disadvantage is that it's XML so it's not the most intuitive way to create documentation for many people (there are editors out there and we have one but most of the developers just end up writing in their favourite text editor as it's easier once you've learned the tags). Images in particular aren't that straight forward (it's akin to coding them in HTML - create the image, save it then create a reference to it). The XML can then be converted to HTML, PDF or whatever for distribution. It supports dividing subsections out into separate sections (which makes it easy to reuse them), templates and so on so there is some good stuff there. It's not for everyone but it's something I'd suggest developers looking at how to do documentation spend 10 minutes looking into. |
|||||||||
|
|
After some research, trial and error, I've ended up using Sphinx. It was originally meant for documenting Python APIs, but works fine for end user documentation too. |
|||||
|
|
A Wiki. Modern Wikis give you version control, simple but powerful editing, and just require a browser. You will then need a special contents page containing listing the links to other pages allowing you to generate a full document by expanding all the wikipages linked to in the contents page. Keep it simple! (note: We don't use this approach as we don't fit your description, but I would encourage you to look into doing it like this) |
|||||
|
|
We have been using AsciiDoc for our needs for the last few years. It is similar to Sphinx except that it works with the Docbook format. It is a simpler markup then Docbook itself. The neat thing is that the documentation is plain text and it allows for the creation of pdfs, xhtml, chm and a number of other formats from a single set of source files. It also is very version control friendly. The nice part about keep the docs in the same repository as your code is that it is very easy to keep it in sync. If I add a new feature I can immediately add the required notes to the document and the technical writer can clean it up later. The downside is that you need to install it under cygwin on windows and make a couple of build scripts to get it to run properly. It is not too challenging though. You can also build different pieces of the documentation. For example, we had a request from a potential customer that wanted to see all of the features/bugs that were added or fixed over the last 2 years. I was able to quickly create a script that built our release notes for the last 2 years into a single pdf (mind you your docs need to be well organized to do something like this). This proved the tool to management. I was looking at switching to sphinx because of the cygwin dependency on windows but one big thing I was never able to figure out was how to setup mapids in sphinx that the help apis could use to popup the chm file to the proper spot from the application. |
|||
|
|
We use DocBook with some customization layers, to produce PDF, HTML and TXT files (for some specific applications). (The key point is we produce XML to PDF software and use it to for rendering. Though Apache FOP is free and may fit your requirements.) DocBook is very good and has a rich vocabulary to produce manuals and references in both electronic and print ready versions, it is easy to customize (page layouts etc). Since it is an XML (readable for humans, not like WordML) it is easy to make your XSLT stylesheets to produce something which best fits your needs. For example, if some day you want to publish all your documentation on a some kind of wiki, you can make a stylesheet for it. I can't even imagine, how someone can use MS Word to make documentation of an average quality. |
|||
|
Web-based documentation is a way to be platform-independent. Most day-to-day documentations, the ones other developers use and are changed constantly on to reflect the truth can work this way. It's easy to use, the learning curve is not too steep and comparatively cheap to set up. For documentation that other users (or developers in different teams/companies use) you should use whatever tool you and the team have but the output format should be something independent like PDF. |
|||
|
|
|
Our external documentation is a combination of PDFs and a well-edited wiki. The wiki is for information that changes on a fairly regular basis (FAQs and informal approaches to problems). The PDFs are aimed towards providing formal documentation and come in a range of styles ranging from detailed API references through to the glossy marketing materials. The workflow normally has a technical writer looking over the internal developer wiki and then messing about with the product in question. After the technical writer is confident that they know the application well enough then they set down to write the reference materials. Marketing usually handle the glossy blurb PDFs. We don't put out Word documents because they are not universally compatible. That's why PDF was invented. |
|||
|
A few years ago we had used a subversion controlled documentation folder (great version control), but we ended up with people using their favorite tools to create their docs and hence you needed quite a few viewers or conversion tools to read them all. In another company most documentation was done on a wiki (easy to learn, great for cross-referencing), but we ended up with people being lazy and not using links to other docs, so gathering all information became tricky. Currently I am working in a team using Google docs (offering many different tools, quite easy to use, everyone uses the same tools) but I still miss Wiki for the nice cross-referencing abilities. My impression is there is no fool-proof documentation system around, it's quality always depends on the team' discipline to stick to project-defined how-to's. And if the going gets tough one of the first victims will always be the documentation tasks, whatever system you use. |
|||
|
|
|
LaTeX
|
|||
|
|
|
We use Microsoft Sharepoint to hold our various documents (usually written in Word). It lets use make new projects and group users into teams as well as letting us integrate with Outlook so we can have a project calendar showing all appointments / meetings. For documenting code, the best documentation is the code itself. |
|||
