As a ramp-up to working on the DocGuide, I am catching up on some editing. As I do so, and at the risk of sounding pedantic or picky, I wanted to share some thoughts with the list. I've been dipping into a bunch of the languishing tutorials and only doing real work on one or two, so I'm not going to point out specific examples, especially since that might be construed as unfair criticism of a particular work. The fact that there is any material at all to edit is a BIG credit to the hard-working volunteer writers who provided it. I hope these thoughts might be helpful to some of the people who have come on board recently and are preparing ideas for future tutorials. Comments and discussion are welcome. You may wish to refer to and comment on: http://fedoraproject.org/wiki/DocsProject/DocumentationGuide 1. Organization: All tutorials and guides should have an introduction. All tutorials should follow the introduction content standards listed on the wiki. Remember that tutorials are *task-oriented*, and not meant to be lectures reduced to XML. Constantly ask yourself: "What are the objectives of this tutorial? What will the user BE ABLE TO DO after reading it? Is what I'm writing fulfilling those objectives? Does it show them what to do?" 2. Indexing: Be mindful of the difference between good sectional organization and indexing. The table of contents should suffice to locate major and even minor topics, *if* the material is organized correctly. An index is used to locate concepts and terms whose location isn't obvious from the table of contents or the organization of the document. There may in fact be no need to index a short tutorial, which can be read in its entirety quickly. Indexing is more important for longer works that a reader is not expected to digest in one sitting. Indexing can still be good in a smaller work as long as it is used judiciously. There is no need to be concerned about indexing every topic that appears in a section. Do not index redundantly against the table of contents. If you have a section that entitled "Using Application XYZ," you should not make an index entry for "XYZ, using." You should expect all readers will read the Introduction section of the tutorial, even if that is not always the case. Technical writers and editors, just like mathematicians or programmers, must at some point rely on a few basic postulates. A programmer rightly expects that if you use his code, you will read the licensing terms, and the function headers. We expect that someone who locates a tutorial will read the introduction to see that it matches the subject material. Therefore indexing material that should be found in the Introduction is redundant and unnecessary. Keep in mind that the Introduction should include a section for each major technology discussed in your tutorial. A tutorial should not have more than two or three major technologies involved, or else you should consider splitting it. 3. The Dreaded "Core Dump": Be wary of using terms with which a new user is not necessarily familiar, if your target audience includes new users. (Your target audience should be defined in the Introduction as required above.) Always write to the level of the *least* experienced user whom you reasonably expect to use your document. Remember that bytes are cheap, and if an explanation requires an extra paragraph, you should write it. See the "References" section below for a different take. A consistent problem with documentation is that it can easily become what my coworkers and I frequently refer to as a "core dump," in the sense that it is an unstructured output of all of the author's (many times considerable) knowledge of a subject. Be wary of this in writing/editing documents. "Core dumps" are not good documentation, and lose their authority quickly for discerning readers. The best way to avoid core dumps is to OUTLINE your document before you begin, as most of us did for composition classes as {pre,}teenagers. Flesh out your outline, and revisit it several times *before* you begin writing. Do the ideas progress logically? Are you fulfilling "dependencies" in the education process by discussing the basics first, before you move on to more complex material? Put yourself in the shoes of your least experienced reader. (If you are unable to remember a time when you were inexperienced, you need to find someone new to the subject to review your document and give you pointers!) 4. References: Using references to other authoritative documents is a good thing. An authoritative document might be another approved FDP tutorial or guide, an official work of the Linux Documentation Project, or a published work (of the dead-tree variety, including online offerings of dead-tree works). Messages on listservs, online forums, news sites, or other sources that do not have a rigorous editorial process are not good references. - - - - - Well, that's it for now. Maybe more later when I have a chance to pore over some of the other stuff in CVS. Have a great weekend! -- Paul W. Frields, RHCE http://paul.frields.org/ gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717 Fedora Documentation Project: http://fedora.redhat.com/projects/docs/
Attachment:
signature.asc
Description: This is a digitally signed message part
-- fedora-docs-list@xxxxxxxxxx To unsubscribe: http://www.redhat.com/mailman/listinfo/fedora-docs-list
