In too many offices, the documentation specialists are isolated from the rest of the team. The programmers usually think of documentation as nonsense, and don't think that writing clear English is a skill even though they can't do it themselves. The doc specialists are frustrated by confusing software which nobody can seem to explain, and insulted by programmers who hold in contempt anyone who can't write code. Since both sides dislike each other it's easier to not talk. This is too bad, because a writer's skills are necessary to program well. Writers can contribute in many more ways than just putting together manuals. Every step of a programming project can be improved by having writers as a part of the team.
A project begins with listening to what users want, and then trying to translate that into a consistent story. If this isn't done, or is done badly, it's likely that the users will be missing things they want, require extra training to understand the system, and possibly reject the system out of hand. Building a system out of the user's language forestalls these problems. This skill, of translating an undifferentiated mass of ideas into a narrative is what writing is. Doing this requires no technical knowledge, just an ability to listen and think, and then translate that into a system. This is an area that writers shine in.
Including writers on the design team can also help because they aren't programmers. Programmers can get bogged down in technical detail to the detriment of the design. Also programmers have a tendency to make up technical excuses for being lazy. Many times programmers will settle for a poor design because a good one seems like too much work. Another thing programmers are lazy about is the look and feel of applications, mostly because fixing cosmetic problems is usually arduous and boring. Having someone on your team that can push back against that mentality is important. It keeps the team honest.
Writers help with the design in other ways. When a writer finds something difficult to document, that's a warning sign. It usually means you need some clarification from the users, or the programmers need to go back to the drawing board and think up something that's easier to explain. Forcing writers to document things that are confusing or ambiguous means forcing bad design on your users. But if writers are full members of the team, they can tell you about these problems before the users see them.
Writers are also part of the test team. Every piece of documentation is also a test plan. The first thing a writer should do after finishing a piece of documentation is fire up the application and test what they've written. If things don't go as they should, that's another warning sign. Either the documentation needs to be rewritten to explain extra steps, the program needs to be fixed or the design needs to be revisited. In any case, the mismatch between documentation and code lets you know that some more work needs to be done.
Writers should be full members of programming teams. They can contribute to the design of the project, and are able to spot problems before the users see them. If writers are considered full team members, they'll be more willing to share problems they're having, which many times are signs of deeper problems in the application. Writers should be brought out of their isolation and into the team.
Showing posts with label Writing. Show all posts
Showing posts with label Writing. Show all posts
Tuesday, March 15, 2011
Tuesday, January 4, 2011
Writing Is Key
There are two things you need to learn before you learn programming. One is typing. If you can’t type, you’re all but illiterate today. Hunt and peck typists refuse to type anything out because it’s so hard for them, so they don’t write documentation, explain problems to users or management, or communicate their design to other programmers. If you can’t type, you’re stuck with face to face communication and cut and paste programming. You’re like a primitive caveman who has to rely on his memory for everything and if he can’t remember it, it doesn’t exist. Typing is necessary.
The second and more important thing you have to learn is how to write. You may think you can’t write. You may have fallen for that left-brain/right-brain hogwash and believe it’s impossible for you to learn to write. You may believe it takes an innate talent to write. You may think that you were cheated out of an education in high school and it’s too late to fix that. You may believe writing is a waste of time. You’d be wrong on all counts.
There’s plenty of community colleges that have writing courses. Such courses are on writing alone and don’t teach to a test, so you aren’t distracted by other junk and can concentrate on learning. You get to choose what to write about, which makes it easier to come up with ideas. You can take the course pass/fail, so you aren’t distracted by the nonsense of grades. Instead, you pay your money and learn a skill. You don’t need to become a great writer; I’m only a passable writer myself. You do need to understand writing enough to be able to express yourself to others. You need to rise above the average illiteracy of today; the clumsy wording and meaningless corporate-speak that is most writing you see at work.
Okay, so you can learn to write; but why would you bother? There’s a million reasons. When you have a problem that’s similar to something that happened six months ago, it’d be useful to have something written down about your earlier solution. When you’re looking at a program you wrote two years ago, it’d be useful to have the code documented, so you can quickly figure out how it works. When you need to add a couple of fixes the users asked for in the last meeting, it’d help to have that list written down, with a clear explanation of what the users wanted. Any program you write must have user documentation, and it’d be easier to hand your doc writer a decent list and description of features instead of spending hours rambling about what you remember coding. When you get a nasty email from the boss, it’d be useful to be able to explain yourself clearly so you don’t get in trouble.
You may be thinking that most of these examples are about things that are no more than three sentences long, so you don’t really need to learn to write. But despite the fact that children are graded and writers are paid by the word, writing isn’t about volume. The skill of writing consists of organizing your thoughts so you can convey them precisely. Even a one sentence description of a function can be improved by someone who knows how to write. And the act of writing, of wrestling with how to say something clearly, will clarify in your mind what you’re trying to do. Writing helps you understand what you need to do even before you start coding.
These skills carry over in another way too. A good writer will take a group of sentences, cut out the unnecessary, clarify the unclear, and rearrange everything until it flows properly. This should sound familiar because this is exactly what a good programmer does when coding. Writing is design. When you write you are exercising the same mental muscles you use when you design and implement a program. So improving your writing skills will not only help you communicate with your boss, your users, and your colleagues; it will also help develop the skills you need when you’re sitting at your desk pounding out code. Writing skills are fundamental to what you do as a programmer.
The second and more important thing you have to learn is how to write. You may think you can’t write. You may have fallen for that left-brain/right-brain hogwash and believe it’s impossible for you to learn to write. You may believe it takes an innate talent to write. You may think that you were cheated out of an education in high school and it’s too late to fix that. You may believe writing is a waste of time. You’d be wrong on all counts.
There’s plenty of community colleges that have writing courses. Such courses are on writing alone and don’t teach to a test, so you aren’t distracted by other junk and can concentrate on learning. You get to choose what to write about, which makes it easier to come up with ideas. You can take the course pass/fail, so you aren’t distracted by the nonsense of grades. Instead, you pay your money and learn a skill. You don’t need to become a great writer; I’m only a passable writer myself. You do need to understand writing enough to be able to express yourself to others. You need to rise above the average illiteracy of today; the clumsy wording and meaningless corporate-speak that is most writing you see at work.
Okay, so you can learn to write; but why would you bother? There’s a million reasons. When you have a problem that’s similar to something that happened six months ago, it’d be useful to have something written down about your earlier solution. When you’re looking at a program you wrote two years ago, it’d be useful to have the code documented, so you can quickly figure out how it works. When you need to add a couple of fixes the users asked for in the last meeting, it’d help to have that list written down, with a clear explanation of what the users wanted. Any program you write must have user documentation, and it’d be easier to hand your doc writer a decent list and description of features instead of spending hours rambling about what you remember coding. When you get a nasty email from the boss, it’d be useful to be able to explain yourself clearly so you don’t get in trouble.
You may be thinking that most of these examples are about things that are no more than three sentences long, so you don’t really need to learn to write. But despite the fact that children are graded and writers are paid by the word, writing isn’t about volume. The skill of writing consists of organizing your thoughts so you can convey them precisely. Even a one sentence description of a function can be improved by someone who knows how to write. And the act of writing, of wrestling with how to say something clearly, will clarify in your mind what you’re trying to do. Writing helps you understand what you need to do even before you start coding.
These skills carry over in another way too. A good writer will take a group of sentences, cut out the unnecessary, clarify the unclear, and rearrange everything until it flows properly. This should sound familiar because this is exactly what a good programmer does when coding. Writing is design. When you write you are exercising the same mental muscles you use when you design and implement a program. So improving your writing skills will not only help you communicate with your boss, your users, and your colleagues; it will also help develop the skills you need when you’re sitting at your desk pounding out code. Writing skills are fundamental to what you do as a programmer.
Subscribe to:
Posts (Atom)