Hi, George!

I worked on a few different projects with different approaches for writing specifications and end-user doccumentation. I have a few otehr observations to add:

I completely agree with you that for small - average-sizeed projects specifications should be written as good as possible. One more thing I know about that this does not works well for very large porjects, because usually you forget after uear of work all details in specifications related to modules developed at start of the project. Instead, it is good idea to split project to a few several projects, phases, iterations or whatever you like to call them. In such case documentation and specifications should be written for each phase separately.

In addition, projects for developing products for selling are VERY different from custom software development projects. When developing something for selling, you require to have speciall approaches to docummenting and maintaining specifications, because they change sooo often that without good approaches docummenting, communications and specification changes would take 2/3 of the overall time spent on such project. In this case it is good to determine so-called "version points" when we have exact specifications for some version of product, and we do not change/improve anything in it till version goes into production and we have some feedback from end users.

Separate subject here is writing help files for end-user. They should be written by a person that did no development or specifications. This is the best case,thoughtakes more time - because such person is the most close to end-user, and thus things obvious for developers and specifications writers are not obvious for such person, so help file will be much better.


Finally, for me it looks like only 1/3 of all customers value the approach with writing complete specifications. During development, we often require to ask general questions like "What versions of VFP should be used", "What versions of browsers we should support in this WEB applciation" and a lot of other questions that are generic and that should usually be explained from start of the project in specifications. In many specificaions we get "I wont something that does something like it is in some other program" and nothing more. When we start to ask questions and determine main points for specifications, it appears that we spend too much time on communication and finally we got unsatisfied by the overall process because it takes too much nerves, time and resourses.

Writing good specifications is VERY valuable skill, but it is also VERY hard. Taking this into account, it is good to use both-side approach in development - have at least 2/3 of specifications, and have developers that also skilled enough to see holes in specifications and ask questions immediately in process of development, as well as track docummentation well. In such case nobody is trying to jump up to stars by trying to get ideal specifications, and work looks more "real". In any case, both parties should look for achieving a goal instead of looking how to save money on anything. Only in case of collaboration from all sides it is possible to work in such model. When customer looks for cheapest solution by saving on every detail instead of achieving goal, it is not possible to work well even with complete specifications < S >.

It was sad to know that at some moment customer does not understand what means "We need more detailed specifications" when he seems, to his mind, provided all information for development. However, things obious for customer are usually far not obvious for developers, and that is why collaboration is required in such case instead pinging each other for who is responsible for extra time spending.


>Every once in, unfortunately, a great while, I find it useful to “go back to basics”. By this I mean going over old textbooks just to see if there’s anything there that might help me in the development process. I did this just recently, and stumbled upon the following sentence, “The worst time to write documentation is when the project is completed.”
>
>This is exactly what I had been doing. Further, for my entire career (nearly 20 years) specifications were something I scribbled on a legal pad and later threw away. That sentence above got me to thinking about how I approached the development process and reminded me of an old programming axiom, “The sooner you start coding, the longer it’s going to take.” Now all jokes aside (such as, “Well that means if I don’t start, I’ll be done yesterday.”), it really has the practical implication of, “The better you plan, the faster you’ll finish”.
>
>As a result of the above, I started writing formal (but rather general) specifications as the project has evolved, I’ve updated the specs, as well as documented (technically) the programs, forms, objects, etc., that I’ve created. My general impression is that once I’m finished, writing the user documentation should be a snap because I know from the technical documentation exactly how things do work, as opposed to how I think they work.
>
>The purpose of this post isn’t to elicit a response per se, but rather spark discussion on this topic. In short, how do you feel about what I’ve just written? How do you approach this?
>
>As Mike Myers on Saturday Night Live used to say in his “Coffee Talk” skit, “Talk amongst yourselves.”:-)