Beefy Boxes and Bandwidth Generously Provided by pair Networks
Keep It Simple, Stupid
 
PerlMonks  

Introduction to Technical Writing/Documentation

by ailie (Friar)
on Dec 07, 2001 at 21:47 UTC ( [id://130249]=perltutorial: print w/replies, xml ) Need Help??

The basic principle of technical writing is simple: Tell them what you're going to tell them. Tell them. Then, tell them what you've told them.

Why am I telling you this? Because, like it or not, documentation is part of programming. Good documentation will make your life substantially easier. Consider this - even if you know your code inside and out without documentation, others may not. Would you prefer that every user pester you with questions, or that your documentation take care of that, leaving you time to code in peace?

This tutorial isn't going to focus on documenting code on a line-by-line basis, or on POD ("Plain Old Documentation"), but rather on the larger picture of how documentation is prepared. Its purpose is not to turn each and every Perl Monk into a technical writer, but rather to give you (the coder) an idea of how documentation is produced.

Obviously, if you're the only person working on a project, it's unlikely you'll hire a technical writer to create in depth documentation. In such a case, you'll end up doing the documentation yourself. If you work in an environment in which documentation is farmed out to a technical writer, don't think you're off the hook. Think of this tutorial as How to Get Along with your Technical Writer 101.

Principles of Technical Writing

The Handbook of Technical Writing, 6th edition (Alred et al), lists five steps to successful technical writing:

  1. Preparation
  2. Research
  3. Organization
  4. Writing a draft
  5. Revision

In the next few sections I will go through these steps in more detail, with an eye to highlighting points particularly relevant to software documentation.

Preparation

Writing requires preparation. You can think of this step as being broken down into four tasks:

  • Establishing the purpose of the document
  • Assessing the audience
  • Determining the scope
  • Selecting the appropriate medium

Let's look at this document. Before I sat down to write this tutorial, I asked myself some questions.

What is the purpose of the tutorial?

To provide an introduction to technical writing/documentation.

Who is the audience and what do I know about them?

The audience is members of the Perl Monks community. This community is focused on Perl. It's a diverse community with wide skill levels from complete novice to Perl gurus, but since this is a tutorial, I'm covering fairly basic material. It's a fairly friendly and informal place, so a conversational writing tone is appropriate.

What is the scope?

This is an introductory tutorial. The purpose is not to turn each and every Perl Monk into a technical writer, but to give an overview of the documentation process.

What is the medium?

Perl Monks, of course! More generally, this tutorial is an online article presented on a web site. This is important: writing for the web is not the same as writing for print or any other media. What works well on paper may not work on the web. The web also has features that print does not, such as the ability to link to more information. Use these features to the fullest.

Research

The purpose of documentation is to convey information. In order to convey information, you must understand it. In this case we are talking about your code, so hopefully you understand it - but can you explain it?

If you have worked with a technical writer, you have undoubtedly faced a barrage of questions. "What does this do?" "What does that do?" "How does one...?" This is research. It is necessary. You can help it along by commenting your code. The expertise of technical writers varies widely. Some are expert coders themselves. Others may not have expertise beyond their tools of the trade. In any case, having comments in your code will help their research and reduce the amount of time they spend pestering you.

How should you comment your code? In The Art of Code Documentation Drew Sikora distinguishes between commenting for developers and commenting a finished program. When your code is still being developed, it is likely being read only by other developers. In this case, simple comments are fine. When code is finished, comments should be expanded into documentation so that users or future developers can get up to speed with what you were thinking when you were developing the program.

If you are not working with a technical writer, you will need to take on more of the research. You may understand your code, but do you understand how the modules used in your code work? What will users of your program need to know about what the program does? Keep in mind the answers to your questions from the preparation stage.

Organization

Poorly organized documentation may in fact be worse than no documentation. Consider what you need to tell users, and how that information can best be conveyed. For example, if you're writing installation instructions for a program, you will want to go with a sequential method of development: step 1, step 2, and so on. If you're writing a history of versions, use a chronological method of development. Choose the method that best suits your subject, your readers, and your purpose.

In software, often used methods of development are division and classification (explain each parts function and how the parts work together) and general-to-specific. In general-to-specific development, you begin with general information about the function of the software, and move to more specific information.

Once you've decided on an organization scheme, prepare an outline. This provides a road map for your writing. How you outline is a personal choice. Personally, I use an iterative approach: I start with a very broad outline, such as

	Technical Writing/Documentation Tutorial
	Introduction
	Principles of Technical Writing
		Preparation
		Research
		Organization
		Draft
		Revision
	Conclusion
	References

I then go through my outline and break categories into sub-categories and sub-sub-categories until I feel I have a clear enough map. For example, I broke the Preparation category up in this manner:

Preparation

  • Purpose
  • Audience
  • Scope
  • Medium

Writing a Draft

Once you have your outline, you can begin writing. Expand your outline into paragraphs. Some advise not worrying about matters such as grammar, spelling, punctuation, and layout at this point. Personally, I find it difficult to follow this advice. I usually write fairly polished drafts. Regardless of your tactic, you will be revising your work in the next step.

You may wish to save the introduction for last, since you will have a better idea of what is covered in the body of the document. You will also need to write a conclusion to your document - remember the basic rule of technical writing:

Tell them what you're going to tell them. (Introduction)
Tell them. (Body)
Tell them what you've told them. (Conclusion)

Revision

Revision is one of the longest steps of this process. In my technical writing text, there's a checklist for all five steps of the writing process. The first four fit on the first page, and revision takes up a page of its own.

When revising, check for completeness and accuracy. Check that your writing is concise, and covers a topic clearly. Check your spelling and grammar. Use spell check, but don't use it as a substitute for proof-reading. Review the mechanics: are abbreviations, acronyms, and initialisms expanded at their first usage?

Don't do your revision in one step. I'm sure many of you have had the experience of spending hours looking for a bug in your code. You give up, frustrated, and the next day come back to see the problem staring out at you, as if in boldface. Likewise, having someone proofread your work is a good idea. How many times have you been frustrated by a bug and posted it on Perl Monks, only to get a quick response from someone else pointing out the problem? The same thing works for revision.

Conclusion

You may regard documentation as a chore. You may regard it as an opportunity to learn. Regardless, you do need to document your code. In this tutorial, I've presented the steps used in technical writing/documentation: preparation, research, organization, writing, and revision.

In preparation, key points discussed were: establishing the purpose, assessing the audience, determining the scope, and selecting the appropriate medium. The research section covered the reasons for research and strategies for commenting code. In organization, methods of development used in software documentation were introduced: sequential, chronological, division and classification, and general-to-specific. Outlining was also discussed. Finally, strategies for writing and revision were covered.

References

Aldred, Gerald J. et al, 2000. Handbook of Technical Writing, 6th edition. Boston: Bedford/St. Martin's.

Sikora, Drew. The Art of Code Documentation. Game Dev. http://www.gamedev.net/reference/programming/features/codedoc/

Replies are listed 'Best First'.
Re: Introduction to Technical Writing/Documentation
by merlyn (Sage) on Dec 07, 2001 at 22:47 UTC
    A few random notes from my 23+ years of tech writing:
    • Words can take a person from point A to point B. If a person isn't at point A, or doesn't want to go to point B, then the text will be a mismatch. The better you define point A, explain it, define point B, explain it, and then accurately keep A and B in mind as you're writing, the more successful you'll be with the readers.
    • As an expansion of the previous point, I write books and columns to a single reader, whom I usually call "Joe". I define what Joe knows at the beginning of the book, and at the end of each chapter, and then I keep Joe in mind as a real, single reader while I'm writing. Seems to work nicely, and keeps me from handwaving or forgetting prerequisities.
    • In product documentation, the manual is the product. If a feature isn't defined, it doesn't exist as far as the user can tell. If a feature is described badly, the user will percieve the product to be a bad product. Thus, do not skimp on the documentation.
    • When you write a piece, read it aloud to a friend, or the wall if you have no friends nearby. If it doesn't make sense when read aloud, start over. That'll keep you from writing stuff that "looks good to your English teacher", but is truly useless in the real world.

    -- Randal L. Schwartz, Perl hacker

      I think that this advice is very good in most all writing and it is a key to keeping your readers attuned to what you want to impart to them. I hate to write documentation because I always feel like I am talking down to my reader, but I don't want to assume too much of there reader. It could be alleviated by clearly stating whom the reader is that I have in my mind. Thank you for your post Merlyn.

      Sparky
Re (tilly) 1: Introduction to Technical Writing/Documentation
by tilly (Archbishop) on Dec 09, 2001 at 00:41 UTC
    First let me add my thanks for a good tutorial on technical writing.

    However I do have one small disagreement. The article that you link to by Drew Sikora offers what I consider to be horrible advice on commenting. He obviously gives short shrift to the real issues with how commenting style ages as code is maintained. He also fails to appreciate the importance and value of making code definitive. When you first write them your bug count in code and comments is approximately the same. But you catch errors in your code. You never see the ones in your comments. So if code and comment disagree (as they will from time to time) the code is rather more likely to be correct. And given that, what is the point of detailed comments that undermine the code? (In fact in some of his demonstration code he has exactly that issue. The comment suggests that += should be =. Yet he thinks that you should gloss over it? Huh?)

    This is not to say that I don't think you should comment. You should. But you shouldn't comment in the ways that he recommends, or about the things that he says you should comment about. I could go on about this at length, but I won't bother doing so now because I already did. :-)

    UPDATE
    s/thrift/shrift/ (thanks to grinder for catching it)

Re: Introduction to Technical Writing/Documentation
by hagen (Friar) on Dec 08, 2001 at 14:29 UTC

    Thanks ailie for a well crafted, and craftily self-referencial, introduction to Technical Writing. ++.

    I'm unable to attribute the following epithet, I heard it said more than twenty years ago...

    "Documentation is like sex...
    When it's good, it's very good, and when it's bad...
    it's better than nothing.!"

    8-) hagen
Re: Introduction to Technical Writing/Documentation
by zemote (Scribe) on Feb 20, 2003 at 16:17 UTC
    How many of you document your code? How many of you forget what you coded. Documenting can only make you a better programmer and be able understand your code better. Great tutorial ailie. The only thing worse than reading someone else's undocumented code is reading your own undocumented code and not having any idea what you were thinking when you wrote that. zemote
Re: Introduction to Technical Writing/Documentation
by BrowserUk (Patriarch) on Jul 28, 2010 at 08:17 UTC
    The basic principle of technical writing is simple: Tell them what you're going to tell them. Tell them. Then, tell them what you've told them.

    What utter rot! This is a meme invented and perpectuated by training companies, to stretch 2 days of material into a 5 day course and so double, or more, their revenue! It's a good way to improve the "feel-the-width" metric of a book also.


    Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.
    "Science is about questioning the status quo. Questioning authority".
    In the absence of evidence, opinion is indistinguishable from prejudice.
      What utter rot!

      Agreed, though it's a failure of technical writing which slavishly copies the format of the spoken presentation.

      One important difference between writing and speaking is that the written word does not necessarily follow a linear chronology. In other words, you don't have to repeat yourself to make a point because the reader can re-read.

        the format of the spoken presentation.

        Even in a spoken presentation, repetition is just filler.

        Some sources try to suggest that it is an application of Spaced Repetition, but this is proven wholly false. For spaced repetition to work, the facts have to be concise and discrete, and must be repeated verbatim. There has also been research that suggests that the timing of repetitions is an important factor in the benefit of repetition, and that the length of the average presentation is simply too short to usefully achieve the benefit of 3 repetitions; even if those repetitions were correctly structured and verbatim.

        With the 'tell'em what you're gonna tell'em; then tell'em; then tell'em whaty've told'em.' meme, the pre & post summaries lack any useful details, so fail to serve as useful reinforcement. Indeed, it has been shown that the preamble serves to cause many of the audience to reach pre-conclusions about the usefulness of all or parts of the session; and/or start anticipating later elements of the talk thereby distracting them from digesting earlier parts that they've pre-concluded to be unimportant.

        There is some merit in summarising a previous dependant session -- "Last time we explored how X led to Y; now we'll see how that helps us to achieve Z" -- but in all cases, written handouts are far more useful than filler summaries, because:

        you don't have to repeat yourself to make a point because the reader can re-read.

        It also leaves more time for looking at some of those details that are traditionally skipped because of "lack of time". Or, allows shorter presentations saving the delegates money; or enabling them to attend more sessions.

        There really is very little merit in the "three Ts" beyond padding trainers saleries and training company coffers.


        Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.
        "Science is about questioning the status quo. Questioning authority".
        In the absence of evidence, opinion is indistinguishable from prejudice.
      Actually, the phrase was an old saw in radio copywriting, where you repeated things three times. The formula does have its applications in technical writing, but it would take a stretch to make it fit. For one, if we wrote everything three times, our instructions would balloon accordingly. Yes, we should give the reader a clue as to what we're going to tell them, and it's a good idea to give a summary at the end. But how many people have the time or interest to wade through all that?
        In my opinion, the "Three T" only applies to presentations, the so called, sales pitch. Technical documenting is serious and the most important portion of it is research, research, research...

        "Actually, the phrase was an old saw in radio copywriting, ..." -- JohnHerald. Performance Today is very irritating that way. I wish my radio clock would shut off when non-instrumental audio is encountered during the 2 hour period. ~_#

    A reply falls below the community's threshold of quality. You may see it by logging in.
Re: Introduction to Technical Writing/Documentation
by Anonymous Monk on Feb 06, 2009 at 19:42 UTC
    In terms of tools, I would recommend using MultiMarkdown to create your documentation. It's a very legible and concise markup language. Here is a nice tutorial on how to use it : http://www.huyng.com/?p=102
      No one asked you in terms of tools

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: perltutorial [id://130249]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others chilling in the Monastery: (3)
As of 2024-03-19 03:54 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found