Documenting for developers and testers

Question

How do you approach writing documentation that both, future developers, and non-technical audiences will have to use? Do you write two separate documents, or try to write one with enough information for both groups? Any other ideas? What are the advantages of doing it your way?

Answer 1

While ideally docs are nice, it usually happens that unless you are paying someone to write them full time (ie. have a technical writer on staff), the first pass at separate docs are going to be incomplete.

I try to subscribe to an "agile" documentation approach:

• make documentation part of the iteration/sprint/time span. This makes sure it's not interrupting the core development process but is instead being realistically included as part of the development time
• only write what is needed. No fluff, just stuff. And only write enough so that you are not wasting time. Docs are hard enough to write as it is. But, that doesn't mean you should be terse in your vocabulary or descriptions. It's a balance of documenting what is useful vs. what is documented elsewhere or just plain obvious.
• make your documentation executable. If at all possible, use unit, integration, functional, user acceptance tests to document your app or process as needed. This is key for me because this means that when I change my code, my docs, or tests, tell me about some discrepency. Maybe something relies on the little tweak I made, but without the ability to execute my assumptions against the real code, there is no way I'll be able to exhastively find this out.
• a wiki is usually good for procedural stuff. Make sure the team has one and can update the info at will. The living aspect of wikis is what makes them most effective and less likely to be out of date.

I'm thinking I'm forgetting something, but that should be a good start.

Answer 2

I basically see it this way: A "future developer" that has no idea about the code until he needs to work on it needs practically the same "overview" information as a non-technical person. Once the developer has a good idea of what's what, he then needs detailed information pertaining only to the portion of the code he needs to work on.

It's much better than sifting through piles and piles of technical details trying to understand the overall structure of the software.

So, one level of docs is sufficient for a developer to "come to terms" with the software as a whole, as well as for a non-technical person to figure things out. The next level gives the details a developer needs to actually work with the code.

Answer 3

We have two documents. The business facing document describes what needs to be done. The technical document describes how to do it. Developers will often refer to both documents, while the business tends to only look at the one. All of our documents are on a wiki so that they are accessible and version controlled. Our documents are not very formal, but have enough content to make sure every one "is on the same page".

Answer 4

The two target audiences are different.

You need a users guide for the users of the program. One useful technique is to write it in the form of a series of questions, and answers like a faq. Try to think of every question a user might need to ask, and answer it. A one stop faq as it were. As new questions come in, you add them to the users guide, and everyone wins.

The other is a technical spec, which is geared toward the maintenance programmer. It discusses things that the developer needs to know, to help get acclimated to the code. File/Table formats/purpose/naming conventions. Notes on internal data structures. A description of the program flow. Discussion of major implementation decisions. Ask yourself, what you would need to know to get an overview of the program structure without looking at the code. That is what you need to achieve in that document.

Answer 5

We write two kind of docs the HLD High level Design (WHAT) which is for the business and the LLD Low Level Design (HOW) where we included the techinical approach. but it depends on the methodology you are up to and the need of the customer to had them

Answer 6

I try to start with a single document with diagrams and flowcharts as well as technical documentation, combined in a wiki format.

This way I can direct project managers to a quick and easy overview of the project, and direct new developers to the same plus links to more technical documentation they need to get their feet wet.

A given audience will gravitate towards what content they need or want to view, so given that both will be present I'm just creating an appropriate view for each group to visit depending on what they need at the time. Sometimes developers can benefit from a high-level view of how this piece of the puzzle fits into the overall project, sometimes project managers can benefit from a low-level look at technical documentation if they're trying to remind themselves why they aren't programmers... (jk, actually they might be looking for some chunk of SQL code to mine data with for instance). :-}