Fog Creek Software
Discussion Board




Advice required: Documentation Writing / Sofware T

Hi all!

I just wanted to know if any of the wise minds around this forum could point me torwards resources for a new job I'm getting into.

I've just been offered a very interesting job in a small company. Part of my duties will be to create / maintain this company's product's docs, whitepapers, etc. so I'd like to know of any resources / advice on writing documentation. I'm not so much interested on the "how tos", on the nuts and bolts of documentation software use (I don't know for sure how they do it actually on the company), but more on something like "style guides" and "dos and dont's" of the _writing_ itself. Specially since English is not my mother tongue (quite obvious one, that!) and I'll have to document both in English and Spanish.

On second thoughts, I'd also like any advice on a good "system" for generating docs. I have used (briefly) LaTeX, and DocBook, and the classical "HTML and play with it"... but is there any "killer app", any "must have" for this?

And now for the second part of the query :) Another thing I'll probably have to do sooner or later (probably sooner than later) is to get myself involved in the testing of the aforementioned products (testing and documentation are part of QA in this company). Any advice / resources / tips on the matter?

I know I'm asking for quite a bit, but I have grown used to the quality of the advice here, so I thought I'd just try to make good use of it ;)

Thanks a lot

Javier Jarava
Thursday, December 19, 2002

I recommend that any documentation that you generate be placed into a source code control archive, just as software is.  This allows you to track revisions or to retrieve older copies of the document.  Visual Source Safe or StarTeam are the two that I've used the most, and find them quite easy to use.  There have been many discussions on this forum on source code control products.

As for which tool to use in the documentation, Microsoft Word is the most popular.

XYZZY
Thursday, December 19, 2002

My last job was as a technical writer producing software documentation for a very small software company. I have a few words of warning for you:

You need to be a very strong advocate of functional specifications. At the company where I worked, there was no spec, and the software was only halfway complete when I had to start writing documentation. So the only place where I could get answers to my questions was directly from the developers. Developers don't like to be bothered. I can understand that. When I'm writing code, I don't like to be bothered either. But I had no other place to turn to for information, so I was contantly bugging them for information.

Also, if there is no spec in place, the software will progress for a while and you will write documentation for it as it goes. Then management will take a look at the software and decide that they don't like some aspect of the interface (or something). Then the developers will have to rework the code, and you'll have to re-do a bunch of documentation. In the project that I was working on, this happened over and over again. All told, I probably ended up rewriting the entire documentation two or three times. It was very frustration.

So, you need to be an advocate for specifications. Volunteer to write them yourself, if you have to. But make sure that they get put into place. You can't write documentation for software that hasn't been designed yet. If there is no spec in place, then the design is just sitting inside of someone's head, and you'll have to badger them incessantly to get that design out into the real world. If the application hasn't been properly designed, then your documentation will be a waste anyway.

Incidentally, it is rarely an option to write documentation after the code is complete. Generally, most small software companies (and large ones for that matter) can't sit around for a month or two after the software is code-complete waiting for documentation.

Benji Smith
Thursday, December 19, 2002

Will you be primarily updating documents and whitepapers?  If so, I'd recommend going with something ubiquitous and straightforward, like Microsoft Word.  Adobe Acrobat's PDF format might be worth looking into, too.

As to "how to"'s: I've found that good technical writing is primarily a matter of good writing.  If you can write well in your target language, you'll have solved 95% of your problems.  You seem to have an excellent grasp of the English language, but it can't hurt to go to a bookstore or Amazon.com and look for a comprehensive guide to English grammar.  I'm a writer for a living, and I often learn new things about my language.

There are quite a few "style guides" for technical writing out there (such as http://www.rbs0.com/tw.htm ).  They're good for general advice, like the use of pronouns, but I find that they tend to provide a lot of advice about extremely specific issues.  So, in general, I recommend searching the web for a few technical writing style guides, and read them, but don't take them as gospel truth.  Read the documentation that already exists at your employer, and use that as a guide.

Here is Google Directory's entry for technical writing:

http://directory.google.com/Top/Arts/Writers_Resources/Non-Fiction/Technical_Writing/

I'm afraid I can't help you with the testing, as I have no advice there.  A Google search for "software testing" would surely be a good place to start.

Have fun!  Technical writing can be a blast.

Brent P. Newhall
Thursday, December 19, 2002

Don't know exactly what your thinking of, but one software tool to check out possibly in place of DocBook would be Help&Manual, at http://www.ec-software.com/ .

Also, of course, Robohelp, which I haven't used.  But Help&Manual is generally better liked from what I can tell.

Herbert Sitz
Thursday, December 19, 2002

A tool that I have used over and over is RoboHelp. It isn't perfect by any means, but it can get the job done.

As far as advice on how to write documentation. I have only ever written end-user documentation and what I have found is try to figure out how the user is going to use the docs. A lot of people don't ever go through the Table of Contents in a normal WinHelp or HTMLHelp scenario, they will look to the Search and Index functions for quick answers. So try to make those features really easy to navigate. Further, try to put as much task-oriented documentation as possible. The user will be wanting to accomplish something, it is good for you to know all (I know it's hard) the ways the user will be trying to use the app. Then you can stear them in the write direction with proper indexing.

Giampiero
Thursday, December 19, 2002

I would second the comments and general recommendation for Help & Manual.

Woodrow Stool
Thursday, December 19, 2002

"Have fun!  Technical writing can be a blast. "

What?! are you kidding me?

wiser
Thursday, December 19, 2002

Um, no, I'm not kidding you.

Apologies in advance if this comes off like a rant, but I'm surprised when people act shocked that other people enjoy some activity that the original person dislikes.  I know that a lot of people dislike writing technical documentation, but I don't see why anyone should act shocked that there's some soul in the world who does like writing it.

Brent P. Newhall
Friday, December 20, 2002

Hi!!

Thanks a lot for the useful tips and pointers ;)

They are very interesting, but sadly some of them (those regarding code docs, and functional specs) not quite what I was looking for - it's my fault, I fear, for I should've made a little more clear what I needed / was looking for :)

I now have a clearer understanding of the possiton I'm being asked to fill, and the documents I'll have to get ready are not Code Documents (code documenting is done by the developers, or at least that is what is hoped), but more on the line of Product Manuals, Training Material, Whitepapers, and the like. I don't think I'll be handling the actual code of the product, but more like "the finished thing" (at least, not
at the beginnig. I'm supposed to branch into testing later on, but the pressing concern right now is product documentation). So the tools I'll be using / needing are more the  kind of "help generating" tools....

Moreover, I've been told that, as there is not a proper Document Management System in place, I'll have to work with the CTO to set one up (at the moment, the little docs there are come from Word + Acobat). So, any tips / software to look into / "ready to run" packaged Documentation Management SW? Being able to have multiple output formast from a single source is a bonus (after all, if I'm the one doing the writing, I'd like to be able to do as little work as possible). Or, should I go the "raw" way, and stick to LaTeX / DocBook, makefiles and that's that?

The company is primarly a Windows shop; very little presence of other OSs, so the apps should be able to run on Windows...

So, for example, how does FogCreek manage to produce their product docs? (assuming it's not a "drop dead secret", but something I can be told?)

Thanks a lot for your help and undertsanding.

Javier Jarava
Sunday, December 22, 2002

Sorry, I guess I'm still not sure why Help&Manual, Robohelp (or several others like them) aren't what you're looking for.  They aren't what programmers use as part of the design process.  They're tools to generate help and manuals for a finished product (thus the name, "Help & Manual").

For example, Help & Manual gives you a single source for managing your document that can be output as any of the following:

-PDF file
-.html files usable by a browser
-Windows "HTMLHelp" file
-Classic WinHelp file
-electronic book format
-export to Word in .rtf format
-print to paper manual with multiple options

I'm not sure what Robohelp's exact output options are, but I'd guess they're much the same.  These tools are essentially the Windows counterpart tools to DocBook.  They probably aren't as flexible as DocBook, but they're much easier to use.

Their whole purpose in life for these programs is to enable you to push your single source of help documentation out into different formats.  They are not programmer tools.  They're for producing help and manual documentation for the users of a program.

As far as I can tell, they're just what you need for everything you mention, except possibly for the whitepapers.  But whitepapers aren't normally an integral part of help system or a manual, so you can just use your tool of choice to write those (Framemaker, Word, Lyx w/Latex on Linux, etc.).

Herbert Sitz
Sunday, December 22, 2002

----
>Sorry, I guess I'm still not sure why Help&Manual,
>Robohelp (or several others like them) aren't
>what you're looking for
-----

It's my fault for not doing my homework properly, or at least not completely.
I visited the pages for those products you mention (specially the "Help&Manual" one, as it's been recommended to me several times, and I noticed all the "integration with development enviroment" features, but I missed on the rest of the features. But I'm downloading it as we speak ;)

Thanks for all the tips & pointers. Do you know if they play nicely with SCM programs? (such a PerForce or Bitkeeper, the ones at use in my "new" company? :)

Thanks a lot

Javier Jarava
Tuesday, December 24, 2002

*  Recent Topics

*  Fog Creek Home