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!
On Sat, 2005-06-25 at 10:28 -0400, Paul W. Frields wrote:
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."
Indexing does feel slightly redundant on the HTML builds on individual tutorials, and I've tended to index more with an eye for future-proofing for other formats. If/when all of the tutorials are shipped together as part of the distribution then help viewers and document search may make use of the DocBook index tags, and so users may not start with the ToC and read forward as they do with the current HTML format.
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.
I tried this and found that I wasn't entirely happy with the result in one tutorial, although it has worked for the other. The problem I found was that the information presented relies on understanding a set of concepts that are familiar to experienced Linux users, but require explanation for others. By moving the concepts out of the Introduction it was possible to present them without making the Introduction lengthy, and allow the experienced reader to skip a clearly defined section of the document after reading the whole Introduction.
The ideal fix for this might be to have a central document of concepts, so we can explain "packages", "repositories" etc. once rather than in individual tutorials.
On Tue, 2005-06-28 at 19:21 +0100, Stuart Ellis wrote:
On Sat, 2005-06-25 at 10:28 -0400, Paul W. Frields wrote:
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."
Indexing does feel slightly redundant on the HTML builds on individual tutorials, and I've tended to index more with an eye for future-proofing for other formats. If/when all of the tutorials are shipped together as part of the distribution then help viewers and document search may make use of the DocBook index tags, and so users may not start with the ToC and read forward as they do with the current HTML format.
As much as I cringe at it whenever I do it, I do think there is some use in having an indexing term that closely resembles the section title. This may help with Google ratings, and as Stuart points out, it helps make documents more modular as the project grows.
I think the key is that doing the close resemblence indexing is less than a bare minimum. There needs to be more meaningful indexing, as well.
For example, I've been using "how to" and "what is"/"what are" whenever a section addresses something like that. This can build quite an impressive list in the index.
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.
I tried this and found that I wasn't entirely happy with the result in one tutorial, although it has worked for the other. The problem I found was that the information presented relies on understanding a set of concepts that are familiar to experienced Linux users, but require explanation for others. By moving the concepts out of the Introduction it was possible to present them without making the Introduction lengthy, and allow the experienced reader to skip a clearly defined section of the document after reading the whole Introduction.
I think you are both discussing slightly different things and are not that far from agreement.
The main focus of a document should be on one or a few closely related technologies.
It seems reasonable to cover any additional concepts that need explanation to help support the overall topic.
For example, an Apache PHP Tutorial might include various pieces about how to update httpd.conf without explaining everything about that conf file.
A guideline might be, if a topic threatens to grow from a <section> to a <chapter> and the topic is mainly out of scope for the document, it deserves its own document and a reference.
I like the idea of moving content to separate background/concept sections for skipping by the knowledgeable.
The ideal fix for this might be to have a central document of concepts, so we can explain "packages", "repositories" etc. once rather than in individual tutorials.
Good idea. We could have a standard section of references, customizing it per document for whatever external concepts might need better understanding.
- Karsten
On Tue, 2005-06-28 at 14:32 -0700, Karsten Wade wrote:
On Tue, 2005-06-28 at 19:21 +0100, Stuart Ellis wrote:
On Sat, 2005-06-25 at 10:28 -0400, Paul W. Frields wrote:
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."
Indexing does feel slightly redundant on the HTML builds on individual tutorials, and I've tended to index more with an eye for future-proofing for other formats. If/when all of the tutorials are shipped together as part of the distribution then help viewers and document search may make use of the DocBook index tags, and so users may not start with the ToC and read forward as they do with the current HTML format.
As much as I cringe at it whenever I do it, I do think there is some use in having an indexing term that closely resembles the section title. This may help with Google ratings, and as Stuart points out, it helps make documents more modular as the project grows.
I think the key is that doing the close resemblence indexing is less than a bare minimum. There needs to be more meaningful indexing, as well.
For example, I've been using "how to" and "what is"/"what are" whenever a section addresses something like that. This can build quite an impressive list in the index.
Yeesh. Well, I will yield graciously if outvoted on this one... I will also make an effort to back out my CVS changes on the yum tutorial on which I've been working, to restore those <indexterm>s.
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.
I tried this and found that I wasn't entirely happy with the result in one tutorial, although it has worked for the other. The problem I found was that the information presented relies on understanding a set of concepts that are familiar to experienced Linux users, but require explanation for others. By moving the concepts out of the Introduction it was possible to present them without making the Introduction lengthy, and allow the experienced reader to skip a clearly defined section of the document after reading the whole Introduction.
I think you are both discussing slightly different things and are not that far from agreement.
The main focus of a document should be on one or a few closely related technologies.
It seems reasonable to cover any additional concepts that need explanation to help support the overall topic.
For example, an Apache PHP Tutorial might include various pieces about how to update httpd.conf without explaining everything about that conf file.
A guideline might be, if a topic threatens to grow from a <section> to a <chapter> and the topic is mainly out of scope for the document, it deserves its own document and a reference.
I like the idea of moving content to separate background/concept sections for skipping by the knowledgeable.
Like Karsten says, we actually agree on this more or less. It's difficult right now to split out those concepts sometimes -- for now -- because we currently have a paucity of material to which we can refer readers. Part of the growth of the project will be demonstrated in how often we can pare down our tutorials since material is covered better separately, like for instance being able to refer people to a Bugzilla Tutorial to file bugs. :-)
The ideal fix for this might be to have a central document of concepts, so we can explain "packages", "repositories" etc. once rather than in individual tutorials.
Good idea. We could have a standard section of references, customizing it per document for whatever external concepts might need better understanding.
We currently have a jargon-buster that could stand some juicing up... it might make an ideal place to put some explanatory material. What say you guys?
On Tue, 2005-06-28 at 18:25 -0400, Paul W. Frields wrote:
On Tue, 2005-06-28 at 14:32 -0700, Karsten Wade wrote:
On Tue, 2005-06-28 at 19:21 +0100, Stuart Ellis wrote:
On Sat, 2005-06-25 at 10:28 -0400, Paul W. Frields wrote:
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."
Indexing does feel slightly redundant on the HTML builds on individual tutorials, and I've tended to index more with an eye for future-proofing for other formats. If/when all of the tutorials are shipped together as part of the distribution then help viewers and document search may make use of the DocBook index tags, and so users may not start with the ToC and read forward as they do with the current HTML format.
As much as I cringe at it whenever I do it, I do think there is some use in having an indexing term that closely resembles the section title. This may help with Google ratings, and as Stuart points out, it helps make documents more modular as the project grows.
I think the key is that doing the close resemblence indexing is less than a bare minimum. There needs to be more meaningful indexing, as well.
For example, I've been using "how to" and "what is"/"what are" whenever a section addresses something like that. This can build quite an impressive list in the index.
Yeesh. Well, I will yield graciously if outvoted on this one... I will also make an effort to back out my CVS changes on the yum tutorial on which I've been working, to restore those <indexterm>s.
I'd be happy to go as far as indexing Guides only, and have no indexing at all for tutorials until it really becomes important. The main thing is making a conscious decision for all documents and running with it until circumstances change.
We currently have a jargon-buster that could stand some juicing up... it might make an ideal place to put some explanatory material. What say you guys?
I've been thinking around this issue for a while, although I wanted to get the existing tutorials out first.
One problem with the current Jargon Buster is that it is open-ended - there are no rules are to what ought to be defined and what ought to be left to Wikipedia.
This is perhaps fixable by having a set of guidelines as to what should be glossaried, and then making sure that the entries are written. (This is actually an offer of work: I would be willing to take this on).
A separate issue is that the glossary format is more terse than explanatory - I don't think that the four paragraphs on repositories currently in the yum tutorial could be replaced entirely with a glossary entry.
Perhaps we could have some canned concepts paragraphs and drop them in each document (as Karsten says), or even perhaps use includes from a bank of XML fragment files (about-packages.xml, about-mirror-sites.xml).
Another approach would be to take the bull by the horns and write an orientation guide to ensure that users have a baseline understanding that we can assume for other documents. That would require some careful scoping, so that it just teaches them how to fish, without getting into trying to document every task.
-
Karsten Wade -
Paul W. Frields -
Stuart Ellis