Every software development project should have a writer. For a big, well funded project this person may have the title of 'technical author' ... Coder hate to document ... write stuff that is entirely unreadable by anyone without a CS/coding background and intimate knowledge of X, Y & Z.

There is some truth to the comments here. But I will add, "who are the documents for?".

Coders need specifications where everything spelled out in great detail. Be it formal specifications or an agile process you have to be able to express the result in binary. There is no room for interpretation. If you are on a large team and assigned Foo class you may well be interested where it fits in the class heirarchy - something a BA or non-cs/it writer cannot reasonably provide.

Management types want to know *what they are spending their money on* and *is this product alligned with my business objectives*. It is here that a *writer* may be of some use, distilling the *bar* product into some language that makes business sense.

Users dont read documents and only want documentation if *all else fails*. But end user documentation is worth it's weight in gold. Many a project has failed because users cant just *read the source*. Hence writers again prove useful in generating documentation.

As a result I never really mandate any one *documentation/specification* process or set of *hard rules*. Each project is different. Instead I try to provide the right balance of documentation between coder, phb and user.

---

---

• Are you posting in the right place? Check out Where do I post X? to know for sure.
• Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:

  <code> <a> <b> <big> <blockquote> <br /> <dd> <dl> <dt> <em> <font> <h1> <h2> <h3> <h4> <h5> <h6> <hr /> <i> <li> <nbsp> <ol> <p> <small> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul>

• Snippets of code should be wrapped in <code> tags not <pre> tags. In fact, <pre> tags should generally be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and possible janitor intervention).
• Want more info? How to link or How to display code and escape characters are good places to start.