How do you deal with technical documentation?

[DAM]

So, we have some pretty hairy documents we produce for our clients and we pretty much just have a word document that someone keeps the master and updates it and loads it to sharepoint. Next person just downloads it and makes changes, repeat. I'm thinking of introducing a wiki for our documentation, but I need some ideas and which direction to take. Has anyone been able to do this? Advice?

Thanks,

dam

 

[kranky]

I had a number of people asking to implement a wiki for this type of thing. We set one up, no one ever used it after the first month. I don't think creating documentation works well in a free-for-all environment. We needed one person to be ultimately responsible to make sure the formatting was uniform, the TOC was correct, etc.

 

[DAM]

Well, ultimately there would be one person in charge, but being able to quickly edit/update a document while being able to track changes seems like a great idea. Kranky, in your experience, it has never been successful?


dam

 

[purbeast0]

here we have template word documents that we basically can fill in whenever we make a new document. we don't really have many people working on 1 document though.

but since it's a software company we DO have a lot of people working on the same files. for that though we use a revision control application, which lets people check out and check in files, and binary files it will only let 1 person check out at a time. it also keeps backups of every revision of the file that was checked in and checked out so that you can see exactly what changed between the files each time.

 

[TastesLikeChicken]

We used this:

http://www.edms.org/

It tracked our technical documentation revision process as well as our engineering drawings.

It worked but was a bit clunky, non-intuitive, and pretty much everyone hated using it. It required a fair sized staff just to keep it properly administered but a few thousand were using it so that was to be expected.

For uniformity all of our tech docs used a common format and were funneled through a single editor, probably one of the best editors I've ever worked with. She was sharp and an absolute stickler for accuracy.

For a smaller company there should at least be a single person tracking document revisions and ensuring quality/uniformity of content. However, I'm well aware of the small amount of respect and consideration documentation gets in most companies and that most aren't willing to put the resources in place to properly control that information.

 

[Queasy]

Word Templates + Visual Source Safe.

The business analysts are typically the only ones that are editing the technical documents, QA has their test plans that they manage, Dev has the documents that they manage and so forth. Read and Edit rights are assigned as appropriate to the groups.