Write The User Manual First Is Waterfall
Some contributors to WriteTheUserManualFirst suggest this is a WaterFall.
There are at some different sub-topics here
- What is WaterFall, really? That question has other pages devoted to it.
- Does the use of the word First in WriteTheUserManualFirst necessarily imply WaterFall? Does insistence on sequence imply WaterFall?
- Are there artifacts generated in a software project (e.g. a UserManual) that should not change rapidly?
- How does a the user manual differ from a user story?
- What is WaterFall, really? That question has other pages devoted to it.
- Some set of requirements will be used to generate code. WriteTheUserManualFirst suggests that these requirements can be collected in a UserManual. Expectations that a project will develop a manual (or any document) then develop code sounds very much like WaterFall, especially if the project believes that the manual can be crafted and completed before any effort is made to code the solution. Any expectation that the manual can be created and then server as the perfect driver for the coding process is doomed to failure. Change happens, and all artifacts should be able to be changed to match changes in the environment, our understanding, maturity, etc, including the manual.
- Is there a difference between WaterfallMethod and WaterfallModel? There are distinct activities in any development process Analysis, Design, Coding, and Testing, sometimes with Specification thrown in the mix. Some people use different words. The WaterfallModel paper is one of the first to identify these activities. There are some who say that the model is not correct because it describes a world where an activity is totally completed and never revised before the next activity begins, and there is exactly on pass through the sequence of activities. Others claim that this is not what the model describes, rather it is what the method prescribes, and that there is a difference. Is 'model' a synonym for 'method' here?
- Does the use of the word First in WriteTheUserManualFirst necessarily imply WaterFall? Does insistence on sequence imply WaterFall?
- There is then debate about the title WriteTheUserManualFirst. The argument is that "Write...First" can only mean that a document is created and completed, never to be revised. Any verbiage in the topic that suggests otherwise cannot correct the glaring flaw in the title that prescribes writing and completing the manual before other work is commenced. There are other suggested titles for the topic. Should we vote on the title that best reflects the content of the topic? What combinations of words best imparts the idea that the manual is modified many many times over the course of the project, interspersed with code modification, and that the manual revision precedes the corresponding modification of code? Whether or not this is a good idea, what is a good WikiWord for the idea? If we can find the right title then we can talk about if the topic is a good idea, a pipe dream, or an AntiPattern.
- You can't insist on a precise ordering under all circumstances. There will be times when some phase will consist of a lot of rapid exploratory coding, possibly with user trials, and then once some version seems promising, further user trials may explore which parts of the system need extra explanation in a manual. I'm not saying this is always the best way to go, I'm saying it cannot be made illegal, yet that is the effect of saying one thing must come first in any phase. There will always be some circumstance when it is appropriate to change the order of things.
- The suggestion that one should merely say that each component must be addressed in every phase is therefore an improvement. But that has exceptions, too. There might be a phase where no manual is requested. Or where the manual is important but no coding needs to be done. Etc.
- From that point of view, at best it is irrelevant whether the manual or the code is the first one to change to better capture the requirements, and at worst, there is some pragmatic reason to do one before the other. Introducing an artificial requirement to always do the manual first, even if you mean first during an iterative process, is going to do harm at times.
- Misgivings over the suggestions are more than terminology or fine tuning. The methodology isn't strong or workable.
- I believe it well known that sometimes it is desirable to do rapid prototyping over many trials to see how things work out in practice. In that circumstance insisting that the manual get updated in order to guide the next extremely rapid tweak of the prototype is nothing but counter-productive and everyone involved would rebel against such an unnatural counter-productive requirement. It smacks of the problems with waterfall again, even though we may only be talking about a small series of short-lived phases. Sometimes, the manual cannot come first in any phase. Sometimes almost any given thing must come first in any phase. Putting an arbitrary restriction on what can come first is inflexible. I read [Parnas1986] this way: Sometimes no model is going to describe what should really happen. Models by their nature are imprecise. They are still useful. What is needed is for rationalized process to accurately represent the results of what happened, not necessarily what actually happened.
- Be aware that you're not making a case for using your methodology at all. The Parnas article is relevant to why to use a methodology, but appears to be irrelevant as to why to use your methodology. The Parnas wasn't intended to be an argument for using my methodology. It was only to argue that 'sometimes it doesn't work' is not a strong objection.
- Are there artifacts generated in a software project (e.g. a UserManual) that should not change rapidly?
- There is no technical reason why the UserManual has more 'inertia' than code. While it is being written, the UserManual is kept in electronic form in word processing files. If, as in often the case these days, we are delivering the UserManual as an on-line hypertext document, we may never have to put it on paper and traditional lead time for publishing disappears. In very complex UserManuals, we may have to compile the source text and emit pdf or chm or something. The physical act of changing the UserManual doesn't get much worse than changing the code. If we do have to actually kill some trees at the end, it will still be better to have the final draft written and proofed no later than when the code is finished.
- The process of writing UserManuals usually involves workers from an entirely different department with different ideas about how to achieve quality. This is an obstacle that doesn't have technical solutions. How can writing staff be agile? Maybe ProgrammersAreWriters and SpecializationIsForInsects, but corporations will divide labor. There are CFOs, programmers, testers, accountants... all expected to perform different functions. The degree of integration necessary to put the UserManual in the middle of the development stream is still rare. If you could have a dedicated writer assigned to your project they will strongly resist demands to rewrite something as frequently as code changes. Technical writers of this era will view continuous changing of text as a waste of time. Unless and until writers of the manual are also the designers of the resulting software, there is not much benefit to changing the manual before the software.
- If the writers are also designing the software, coders benefit because the specifications stay close to the current evolving understanding of the requirements. Clients would get a manual that was more than an inventory of buttons and screens. It would also add context discovered as the product was developed and give them better ideas of how to make their own work more effective with the product. We might generate an artifact that really added value to the product.
- We'd have to find people who both wrote and designed. Current corporate cultures tend to specialization and this concept would require generalization.
- How does a the user manual differ from a user story?
[Parnas1986] Dave L. Parnas and Paul C. Clements, A RATIONAL DESIGN PROCESS: HOW AND WHY TO FAKE IT for IEEE Transactions on Software Engineering Vol. SE-12, No. 2, February, 1986 pp. 251-257, reprinted as Ch. 18 of "Software Fundamentals: Collected Papers by David L. Parnas, ed D. M. Hoffman and D. M. Weiss, Addison-Wesley, 2001, ISBN 0-201-70369-6 also at http://cobolreport.com/columnists/parnas&clements/09152003.asp
See: WaterfallMethodology, WaterFall, WaterfallMethod, WaterfallModel, WaterfallSyndrome, TestDrivenDevelopment