Fog Creek Software
Discussion Board




Writing technical documentation

I have been reading this discuss forum for a while. It's been a great source of information for me. Thank you all.
I just finished developing a enterprise portal single handedly for a company to which I am working as a sub-contractor. This was my first contracting project.
Now I have to write the technical documentation(not end-user guide, but the documentation for the use of in-house developers) for it.
Can you people suggest me some good links, which provide some basic guidelines for writing technical documentation for web applications? Thanks for all your help.

Yaniv
Friday, June 21, 2002

Don't try to hard, just throw together some diagrams, brief description of your object/procedures, caveats, installation requirements, etc. If their in-house staff cannot maintain the system written by a "single" programmer, no documentation in the world will help them.

Humbug
Friday, June 21, 2002

Have a look at automated tools: I swear by Doxygen [ http://www.doxygen.org ]; It's free, it gets the dob jone beautifully (including, among other things, LaTeX manuals, ,CHM files that Visual Studio will happily look up when you press F1, and html docs with an internal search engine). It will do some diagrams for you as well.

Doxygen documents Java and C/C++ code - and with some help, PHP code as well; Is that the kind of docs you need to write? You need to provide more info about the environment.

Regardless of whether this level of doc is what you need ...

I find that good documentation starts with a well-worked example that IS characteristic of real life and that DOESN'T make too many unrealistic assumptions (such as "no need for any kind of error checking"); The example has to be complete, working, and doing something useful. Better examples can be walked through without sitting at a terminal and typing things. An excellent example of how this should be done is the FLTK manual [ http://www.fltk.org ], which is also an amazing example of a simple, effective design that's also concise and efficient.

If the level you're aiming for is lower (e.g., the developers that are going to read the docs mostly know HTML and a little JavaScript), then I will offer the following advice (despite, no doubt, being shouted at by other people in this forum) - the HTML should be self evident. If you feel you need anything more than a description of the application state machine, the user guide, and very general overview - you're probably aiming for the wrong audience.

Ori Berger
Friday, June 21, 2002

I can recommend the paper "Technical Writing Made Easier".  You will find it at  http://www.icsharpcode.net/TechNotes/

Bernard Vander Beken
Friday, June 21, 2002

Thanks for the responses so far.
I developed this intranet portal using ASP, VBScript, HTML, MS-IIS etc.
The documentation is for the in-house developerd who know a good bit about ASP etc.
They were involved in the requirement gathering writing specification process. But I did all the coding on my own.
Now this documents main purpose is if they have to add any new features in the future and I am not around, then they should be able understand all the source files etc.
I am just looking for some articles which will explain the basic elements of such a documentation etc. Thanks once again.

Yaniv
Friday, June 21, 2002

I agree with Humbug.  Make it minimal, make it concise, do not make it a how-to.

I have seen many documentation projects started, based primarily on the whines of "we don't have documentation".  All of those efforts were essentially failures, as despite the volume and quality of the documentation produced, the whines still continued.  The documentation was never read, never maintained and was eventually fodder into yet another documentation project. 

I eventually reached the conclusion that documentation isn't the problem nor was it the solution. 

The problem that the documentation was expected to solve, was the quest for "instant knowledge and expertise" that could be obtained by the person without any effort on his part. 

There is no solution to a problem with this requirement.

Joe AA.
Friday, June 21, 2002

Joe AA:
"... The problem that the documentation was expected to solve, was the quest for "instant knowledge and expertise" that could be obtained by the person without any effort on his part.

There is no solution to a problem with this requirement.  ..."

Couldn't agree more. Documentation processes that I have been witness to have been pretty useless, even the ones where a lot of determined effort took place from all parties. Where docs are necesaary I just keep it really simple.

Joels guide on technical writing is good here, but you need some kind of buy-in from the rest of your team. Many managers and developers see the presence of documentation as some kind of healthy-glow about their company. Documentation provides no purpose unless it is read. If it is not read, or if it is inaccurate/ out of date it can be worse than if there was no documentation at all.

Keep the docs simple, an install guideis necessary, as is a FAQ (you will have to put in your own questions though). As technical documentation goes, some document that correlates on screen detail with the source files that deal with it. Consider that all you are giving is an up to speed guide for their inhouse guys. You have got source comments, and thatsa what they will use to maintian it.

Richard
Monday, June 24, 2002

*  Recent Topics

*  Fog Creek Home