views:

326

answers:

9

In your team, how is documentation written?

Is there someone assigned to the task? Is there a technical documentation writer?

Please elaborate for:

  • User documentation
  • System Administration docs
  • Development docs
+1  A: 
  • User documentation is written by the usability testers.
  • Sysadmin documentation is written together by the developers and sysadmins.
  • Development docs? O_o
Lars Mæhlum
+1  A: 
  • User documentation: Me System
  • Administration docs: Me (assuming you mean application administration)
  • Development docs: Me

Yeah, we're in the "lone gun" type shop around here, but that's where some well crafted templates come in. 8^D

Dillie-O
+2  A: 

Since answering how things work for my team fails to protect the guilty, I will answer with my thoughts for the "ideal team."

  • Development Documents - Written by the developers as they work, with a double check done once the code is checked in to ensure that the documents are accurate. In an ideal world, the documents would be checked out/in at the same time the code is checked out/in.
  • System Administration Documents - Written by the developers with the assistance of potential system administrators to ensure that confusing issues are identified and documented from the beginning.
  • User Documents - Ideally, written by individuals acting as normal users who have been trained in the software by the developers. Additionally, users should be shown the manuals prior to release and asked to preform tasks based upon the documentation to ensure that it is clear enough.

Except for the development documentation, in a perfect would you would have someone who is both technically competent and able to write doing the documentation. This wouldn't necessarily have to be a dedicated technical writer, but would be useful to have someone who is a part of the project team doing documentation.

Rob
+1  A: 

User Docs: copywriter, technicalwriter Dev Docs: if you need them, it should be part of the task written.

DevelopingChris
+2  A: 
  • User documentation - Testers
  • System Administration docs - Sysadmins or Developers (You answered this partially yourself)
  • Development docs - I assume this means program specifications and other development artifacts. These are written by programmers/developers or Designers/Architechs
Pascal
+1  A: 

The User Documentation is primarily written by our Communications department, who also write up Feature Requests and talk with the Clients about bugs and other problems.

Anything on the System or Code level is written by the Developers responsible for the code if it needs any explaining.

DyreSchlock
+2  A: 

We have a small dev team (8) and smaller support team (4). Historically our user documentation (a 200+ page chm) was written mostly by members of tech support (=usability testers), as they had a better knowledge of customer terminology and work practices. These days we occasionally have the luxury of getting the developers involved, now that the product is feature-rich and much more robust. Having said that, we'd ideally like some wiki-like doc tool that allows our distributors and power-users to contribute.

JV
A: 

As a developer I would prefer to explain how a product works to a user and have the user write the documentation because they will cover things that seem obvious to me but not the average user.

I think it is like translating between languages. Have you ever gotten a product and you could obviously tell that the person who wrote the manual didn't speak English natively? From my little knowledge of languages it seems that it works better for people to translate into their native language than out of their native language.

James A. N. Stauffer
+2  A: 

We have 3 types of documentation:

  1. Technical Design - this one is written by the developers and is generally intended for developers - has details on the code changes, how it fits in the architecture etc
  2. Implementation documentation - this is what do you need to install it, common pitfalls etc. It's done by an Implementation analyst that's closely attached to the development team. This is the documentation that an Administrator would use since it has the most verbose explanation of parameters, logs etc minus the "too technical" details about the code itself.
  3. User documentation - this is done by a Technical writing department and is about how to use the software.
Svet