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. -- Stuart Ellis stuart@xxxxxxxx Fedora Documentation Project: http://fedora.redhat.com/projects/docs/ GPG key ID: 7098ABEA GPG key fingerprint: 68B0 E291 FB19 C845 E60E 9569 292E E365 7098 ABEA
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
