Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I am working in a small team on a large complex software project. I want to document all requirements, but I've been told by my manager that it is waste of time.

I have tried the same with design and functionality, and I encountered the same discouragement.

I am responsible for anything that goes wrong, and obviously, I don't remember everything. Still, I've been told not to create documentation.

How should I approach this problem?

share|improve this question

migrated from stackoverflow.com Jul 28 '11 at 22:47

This question came from our site for professional and enthusiast programmers.

3  
I wish, I have the job under this boss –  Rasel Jul 28 '11 at 11:42
    
What is your boss' current system for making sure that the project is on track and ensuring that it will meet requirements when completed? –  user16764 Mar 15 '12 at 17:39

5 Answers 5

Listen to your boss - s/he's right.

what s/he might be reacting against is a long, exhaustive effort to produce documents without value that will never be read and will soon go out of synch.

Your best documentation is the code itself. Write it so that it's readable and self-documenting. It will always be the final artibiter for questions about what is currently in production.

If you think you need to document something important, do it quickly and quietly. Don't worry about making it perfect; do enough to save the thought and get back to coding.

You're an expensive, scarce resource. Find a cheaper, more junior person to produce that documentation if you can.

share|improve this answer
7  
I think s/he might be right, rather than is right. It's true that in our industry, people more often create too much documentation rather than too little. But there is such a thing as too little. Requirements, to take this example, are something that should be documented very precisely, because there can be huge pain and cost if work is done against requirements which are wrong, or imprecise, or change later. –  Tom Anderson Jul 28 '11 at 11:45
8  
Requirements come from customers, not developers. If the developer is writing the requirements along something is very wrong. –  duffymo Jul 28 '11 at 11:49
3  
+1 for "If you think you need to document something important, do it", +0.5 for "do it quickly and quietly". -0.25 for "Don't worry about making it perfect", -0.25 for "Find a cheaper, more junior person to produce that documentation". If it needs to be done, do it, and do it quickly, but do it properly. If there's something that a developer knows that needs to be captured, then it needs to be captured, and i don't believe that's something that can be handed off to someone less technical. I'm not advocating that developers write the user manuals, but they do need to write the technical docs. –  Tom Anderson Jul 28 '11 at 11:49
2  
About the role of writing requirements: true! But if you have a customer who doesn't write requirements adequately, then it might be sensible, from both practical and arse-covering perspectives, for the development team to record them properly. –  Tom Anderson Jul 28 '11 at 11:51
    
I'd justify a junior developer by saying it may be inefficient, but it's cheaper and not very important. I would not want my best developer writing docs that no one else will read. The fundamental question is: "Do we agree that documentation has value? If yes, what form should it take, how extensive should it be, and who is the audience?" None of those questions have been answered here. We're all making our own assumptions. I'll make mine explicit: I don't think docs are important. –  duffymo Jul 28 '11 at 12:14

Well, now you know better than to ask.

In your shoes, I think I'd try to do both as informally as possible. It's not anything you can hold others to, but at least you'd have something written down to refer back to. That's kinda important when you have to go home and sleep and come back the next day on occasion.

If you are caught doing it, just tell the truth: You have to do it. Design in particular is an inherent part of any creative activity. My father-in-law (an ex-English teacher) creates outlines and rough-drafts for his vacation postcard messages. No matter how small and boxy the building you are sitting in right now, I guarantee you that somewhere there exists a blueprint for it.

Some activities are so trivial that you can come up with a design and keep it in your head without much effort, but most programs that do something useful will not be in that trivial category.

share|improve this answer
2  
+1. Don't ask permission to do the right thing. If you can just make things 1% better a month, at the end of two years, things are almost 25% better, and people will notice that - even people who discouraged you from making it better. –  Scott Wilson Jul 28 '11 at 23:05

Documentation is only worth doing if:

  1. People actually read it (most developers I know prefer to look at the code itself rather than documentation).
  2. In the rare event that 1) does occur the documentation is accurate, complete, up-to-date and adds something that the code itself cannot.

I have spent many hours writing docs for audit/compliance purposes which are literally never looked at.

share|improve this answer
5  
I am not reading 100 classes to figure out what is going on. I would rather read 6 pages in Word doc. –  Job Jul 29 '11 at 1:25
1  
I read the Qt docs. I don't think I'd rather go through the whole of the Qt source code, try to understand how the different classes/methods interact/function and write my code as it was intended to be written without the help of the docs. Even if I could do that, and had a few spare months to waste. –  muntoo Sep 8 '11 at 2:15
    
Job, how do you know that those 6 pages have kept up with the code (or ever really represented them). Maybe a little out of date, maybe a lot, seems kinda dangerous. Tempted to say high-level ok, but that changes over time too. –  Michael Durrant Mar 15 '12 at 21:46

I think this might be more appropriate for programmers.stackexchange.com (I'm pretty new here so not sure)

Regarding documenting requirements...I kind of agree with your boss that it is can be a waste of time to make detailed documentation of requirements. It might make you not see the forest because of all the trees. Document the important stuff and try to get a sense of everything in your head.

share|improve this answer

If there is no documentation whatsoever you are in a no win situation with one caveat.

If you allow the code to be the documentation, like some suggest, when a feature "doesn't work" you might be able to say "It works just like the code says it should" but the manager can then say "The code should have never worked this way." and that is the end of the argument with the coders loosing.

Unless there are tests AND the manager signs off on the tests! Then you can say "The tests say it should work that way." and nobody can really argue with you.

So write tests because they are not "a waist of time" and get the manager to verify the correctness of the tests and all is good in the world.

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.