In the past couple of years, I've worked on two projects.

The first one, we used a very agile methodology. It was very much developer driven. As such, changes were very quick and rapid. Code quality was high becuase it was a new system. There was an emphasis on group ownership of the project and knowledge sharing. Most knowledge transfer with new staff etc. was conducted just by walking someone through the code or system and most staff members on the project knew enough of the project to do that.

The project I thought was successful but one of the regrets I have is the amount of documentation was probably inadequate long term. We had a bunch of user stories which were short term specs only relevant for the sprint, and a a bunch of master specs outlining the business processes that was long term which we would keep up to date. We had no tech specs other than a oneNote page with user logins and links to test envrionments/servers etc.

The problem was keeping a balance between putting enough in there so that it would be helpful and not so much that no one will want to read it and be a burden to maintain. I don't think we ever found that balance. The master specs were probably too generic to be useful to someone that wants to understand the system.

The second project is completely opposite. It's an old system and it's very big. We use a waterfall methodology. This project is very much tester driven. As such we have probably too much documentation - there are thousands of pages in hundreds of word documents and there is duplication everywhere. (eg. documents with the same or very similar introduction texts)

There is a big emphasis on keeping this mammoth of documentation perfect. Creating a simple change to the system requires identifying which documents is affected and making minor changes to all of them.

We document things to levels that's probably not neccessary (eg. I found a doco the other day where the File Save dialog in IE was documented) and there is an emphasis on being correct over being readable.

In short, we have half a dozen Business Analysts and their job consists more of keeping the documentation up to date than of actual analysis.

I think both of these projects have bad practices and what would be optimal is somewhere in between the two. This balance probably depends on the system as well, so how do you decide how much documentation you need and also how to structure it so that maintaining doesn't become more cost than benefit.

EDIT - Hi, sorry should've mentioned it before all the answers came along (I only was just able to check). I'm primarily focused on non-technical business requirements here - those that can be consumed not just by developers (audiences may include BAs, managers, testers, stakeholders etc.)

  • You talk about "documentation" which is not very clear. There are lots of different approaches on documentation and different types of it. You can't find a one size fits all, documentation for developers and implementation partners is different compared to end-user documentation. Which one are you talking about and where do you have most issues? Commented Sep 25, 2013 at 6:51
  • 2
    This recent article is relevant: stevelosh.com/blog/2013/09/teach-dont-tell
    – Roman Susi
    Commented Sep 25, 2013 at 8:00
  • @LucFranken - I'm mainly referring to non-technical documentation in this case, like use cases / user stories etc. Probably should've mentioned that!
    – RoboShop
    Commented Sep 25, 2013 at 23:46
  • That's a big issue, update your question I think. The answers you got now are more related to technical documentation which is not the answer on your question. Take a loook at some other posts here like: stackoverflow.com/a/14054368/1177905 Interesting article: justwriteclick.com/2007/07/02/… There is a lot available here. You might go as far as creating videos which show functionality or using screenshots. If it takes a lot of work you might even generate screenshots with an automated process to improve speed. Commented Sep 26, 2013 at 7:32

3 Answers 3


For design/architecture documentation, I recommend the following approach to our architects and developers:

  1. Use the documentation as a contract at team borders and outside world (APIs, database scheme). That should be available before development of the corresponding parts starts. And because it is a contract, no side may change it without agreement of affected parties
  2. don't put anything in the documentation which is in the code or which is better explained as a comment in the code. So don't bloat it with lists of internal methods and their parameters.
  3. But explain everything in the documentation which is NOT in the code. This includes:
    • system overview - for education of new team members, or just to avoid explaining it again and again
    • any guidelines or strategies which you want to have followed through by development (Kind of contract for your team)
    • architecture or design decisions, and why you picked one alternative over others. You probably put a lot of work and thinking in these decisions, and you will want to avoid that someone changes these decisions without knowing the impact. Some of these decisions create technical debt, and it is a good idea to have it written down so you can work on that later.
    • any deviations from guidelines which you might have in your company, any why. For transparency.
    • risks you see and their potential impact (e.g. a your system might have a dependency on a component which is not ready yet, or you might loose some key resources). This is especially important if someone else forced you to take these risks.

I don't think there is any "correct" answer to this question. Really documentation needs to be succinct and as simple as possible for the target user group.

Also it pays to think of how the system might grow during the planning process and make changes to the documentation structure clear from the beginning and also ensure all people contributing to the docs follow a particular pattern (templates etc).

Think of it like good code, make really broad top-level sections that can be drilled into for progressively more and more information

Hope this helps!

  • I feel in a lot of ways it's much harder writing good doco than writing good code. Code is written for generally one audience (devs) whereas there's so many different types of people or reasons for which you may need doco. It's like having to predict the future.
    – RoboShop
    Commented Sep 25, 2013 at 5:04
  • It is more difficult that's for sure. Start with a broad set of categories than encompasses the core aspects of the application and then proceed to explain in deeper and deeper detail what each function does. Really the most important thing is to determine the audience for the document and then look at the system through their eyes following only the documentation to complete a task. Wiki software like Atlassian Confluence really makes things easier with searches and other cool features. Also screenshots of the app in action are excellent! Commented Sep 25, 2013 at 6:10

At the very minimum, I would consider documentation of all major functions and classes and the params they take and the methods/properties they use to be a requirement for a completed project. This can be done most easily as comments within the code base or by using a wiki, or with something similar to PHPdoc where you add special notations to the comment block above the function or class. It only takes a few minutes to add relevant comments to code, so doing it this way is relatively painless, especially if you make it a requirement that developers working on that code later also update the documentation. Even the original coder themselves won't remember everything six months after they have finished that project. The hard part here is getting everyone disciplined to do it, because honestly, few devs like to write documentation.

Specs, wireframes and development notes should always be kept, even if made redundant later (for historical purposes.) If they can be kept in a digital, searchable format (wiki, website with search functionality, database) then that greatly cuts down the time required to find something.

Btw, I agree that employing six business analysts just to keep documentation up to date seems like a waste of resources, but some projects (especially those paid for with government grants) may require it as a condition of funding.

Not the answer you're looking for? Browse other questions tagged or ask your own question.