Writing Software Documentation - Chapter 6
Writing Software Documentation
Chapter 6
This chapter was involved with planning and writing documentation. This process has been divided into nine steps.
1) Start The Project – In the old days, one writer could sit down with a program and figure it out for himself. This is no longer the case, and most documentation is done in teams. A Development Team is composed of the programmers who created the software, while a Writing Team is made up of just writers.
2) Perform User Analysis – In any situation with giving directions, it is good to know how much your audience already knows. The purpose of this step is to ascertain that.
3) Design Documents – Form a template for how the help system will look and work. Do this for a tutorial, procedure, and reference in mind.
4) Plan the Documentation Project – Form a timeline for who does what and when.
5) Write the Alpha Draft – This is a preliminary version of the documentation.
6) Conduct Reviews and Tests – Make sure your documentation is on target.
7) Revise and Edit – Standard writing procedure.
8) Write a Final Draft – Again, standard writing procedure.
9) Conduct a Field Evaluation – This is when you go out and make sure Johnny Enduser is able to use your documentation effectively.
There are two primary development plans:
1) The Waterfall Method – One stage comes after another, and one cannot begin until the previous one has been completed. The easiest method to start up, it is also the least efficient.
2) The Rapid-Development Method – Writing and planning happen independently of each other; one portion of the team focuses on user needs and proper format, while the other focuses on the raw text required. Once a format is decided upon, the text is absorbed into it. Far faster to implement than Waterfall Method, Rapid-Development also calls for a higher team-work capability.
posted by Lilith Singer | 8:27 AM
11 Comments:
My reaction to this chapter: With all the suggested steps, can a project ever get done in a timely fashion. I think that has to do with my lack of patience. There are some projects I'm involved with that do rise to the level of needing a project manager, who is at an IT or IS level. We spend an awful lot of time justifying what we want to do to people who don't have to actually do it. There seems to be heavy emphasis on following a project protocol, but without time for user testing.
Lest we all get lumps in our throat thinking about the complexity of managing documentation requirements during a major software development project - please be aware that a lot of the pain is taken out of the process through the use of modern software development automation tools. RAD tools such as the Rational Suite (i.e., Rational Rose/Requisite Pro/Enterprise Suite, etc.) integrate software development with associated documentation. Much of the documentation is automatically generated prior to the technical writer's involvement.
Barker's text is teaching us theory and does so by describing a manual process. In practice, however, much of the work in developing documentation is automated and integrated with the software engineering toolset.
In a way, I’m very relieved to read your reply, Carl. It’s a bit comforting to know that in a project like Barker describes we won’t be doing ALL of these steps. I don’t say this in a way to get out of doing extra work, but because of the complexity that appears to be involved. Covering all of these nine steps that are described could lead to some mismanagement along the way. For example, I could focus too much on planning the project and neglect some vital part of user tests in field evaluations. It’s just good to know that we’ll be getting some support along the way.
Like Anne, thinking about all of the steps involved in completing a project can be rather overwhelming! Even with the small design jobs that I work on myself at my job, I tend to get disorganized and forget about deadlines. The 4th step is really something that's important in my job - planning the project is something that I often overlook. Although making a timeline sometimes seems like extra time & work, it is worth it in the long run to have everything planned out to meet the deadline.
It's all in the prep work. I noticed that four of the nine steps for developing a document project are planning stages. Half the battle is done before you ever begin typing!
I'm a bit put off that the first step mentioned is "start the project," because it seems a little lazy on the part of the writer. I think a more accurate description of the step is "analyze your situation." What is the purpose? The scope? The capabilities? The budget? Who is going to be involved? This is the point where you get all your information straight before you even start planning; sort of like a planning stage for your planning stage.
Interesting to know that there are software programs that are designed to do much of this for us, because that could save companies a lot of money and productivity by automating repetitive procedures. I feel I am much better prepared for a job in the field, though, when I know the theory behind something. I prefer to know how to do something myself if I have to. Software can't always be right.
Once again, I have to say that I love reading Carl's piece. He is telling us the way it works in the "real" world, and he is not just relying on theory (but this is a college course, and theory is what schools teach . . .). I'm really glad to hear that a lot of the writing tasks are automated by integrated software.
Even though there seems to be an overabundance of steps, the writing process follows a quite logical sequence. Every document needs to be planned, written, and rewritten if you wish to produce something that has some quality.
I think that one of the most important things mentioned here is to know your audience or perform a user analysis. A lot of time and energy can be saved by knowing who is going to be reading your instructions. And, like Anne mentioned, there are so many steps and procedures that it can be quite overwhelming trying to actually complete something. I'm also glad to have someone like Carl with experience in the industry to let us know that all of these steps are not necessarily needed in each and every project! It just seems like when things get this detailed its a wonder that anything ever gets done.
It does all sound a bit confusing. I would think the waterfall method would work better as only one thing is done at a time. I do understand the need for the Rapid Development Method when time is of the essence and things need to get done quickly such as with a new product release. It would be interesting to work with a team to work on a project.
This chapter brouight back memories of 472 last semester. All of the students were acting project managers. I didn't do too well in the class so I kinda wish I had this book before hand.
Team work, team work, and more team work is what documentation planning and writing is about. Once you have developed your team you may begin. This is true at least for large scale documents. In a smaller company the tech writer may be a one person show doing everything.
I see the need for teams to have proper developement but when it comes to the development process I am torn. I understand rapid developemtn is quicker but I think it would have a higher rate of obstacles and the level of team work needed to preform it successfully would be hard to obtain. The waterfall method everyone is used to and it gives you mroe opportunities to check yourself and others in the development process.
Post a Comment
<< Home