On Sat, 2004-09-04 at 18:36, tuxxer wrote: > > 1. Don't overuse "most of," "typically," "usually," "many." These water > > down your instructions and make the tutorial sound wishy-washy, as if > > you're trying to CYA. A document the length of a typical tutorial can't > > possibly cover every single case, and shouldn't try. Your tips should > > adequately cover a stock installation of Fedora Core, in the present > > version. Don't state this beyond the context of your document's goal(s); > > the fact that it's going to be an official Fedora Doc makes this the > > case. (Guilty) > > I think that it just implies that the author is aware, that his way > isn't the only way. But that's also a matter of perspective, and > nuance. You can include a single sentence in the introduction addressing this point, if you feel it's necessary. We are offering our documents as the "official" word on Fedora, so while they can't completely address every possible configuration or edge case, they should be reasonably complete. If you feel your tutorial doesn't cover enough cases to be authoritative, you should either research the issue some more, or solicit the opinions of other knowledgeable parties. When I was working on my usb-hotplug-tutorial, a helpful third party pointed out that I had left out a couple major technical issues that really needed to be addressed. I reworked the tutorial to take advantage of existing advice from a pretty authoritative source. [...snip...] > > 6. This is a matter of content: Don't cover updates (up2date or yum) in > > a tutorial about system hardening, beyond stating the user should pull > > system updates. Direct the reader to other resources. If every tutorial > > author does this, the aggregate wasted time will be substantial. There > > may not be an "official" update-tutorial to link to right now, but > > that's fine. Simply leave a place marker; there's a tutorial on the way > > for that subject. When it shows up, add a <ulink> to it in your > > document. > > > > (*** NOTE: I think this brings up an interesting side point, which is > > that the yum/up2date tutorial currently in process [1] needs some > > editorial lovin'. Once that's done, any author can point to the finished > > document at the &FDPDOCS-URL; site. That's what this tutorial should do. > > ***) > > Understood and agreed. However, I think that there is some value in > glossing over certain procedures (or re-presenting them) which might > otherwise be covered elsewhere, and thus referenced in your document. > Continuously referencing other material makes the document > discontinuous, and sometimes difficult to read. Overuse can even render > your document useless to the "average" user. You end up with a document > like: > > How to harden: > > Accomplish this task described in this other document: > > http://foo.doc.com/first_ref/ > > Then accomplish the task described in this other document: > > http://foo.doc.com/second_ref/ > [...snip...] > etc., etc. ad nauseum..... > > You're not really providing the reader with a tutorial, just a list of > links that they probably could have found on some Joe Schmoe's website > hosted out of his garage. ;) A tutorial should be *reasonably* self-contained, so I would hope this wouldn't happen. Otherwise the writer should revisit the scope. > Now if the document could be included (as an entity???), so that work > isn't duplicated, but your document actually contains the same > instructions, that might have value. This is an interesting idea, and certainly the idea of updating the system seems universal enough to warrant such a treatment. A paragraph or even just a couple sentences, with one or two command lines ("up2date -u" and/or "yum update"), is sufficient to cover this topic. If we can find a concise way of covering this issue, we could duplicate it for other tutorials that need the same material. How does that sound? [...snip...] > > 7. Leave out statements like "One of the most important things to do is > > to mind your P's and Q's." If it's important, the reader expects it to > > be in your tutorial. The converse is also true: if it's in your > > tutorial, the reader expects it is important, especially if you use a > > whole section for it. Merely state, "Mind your P's and Q's." Then > > elaborate as required. If the whole section concerns how to mind one's > > P's and Q's, you may be able to leave this sentence out entirely. > > (Guilty) > > OK, so how do you say ... "This section is important. However, THIS > section is REALLY important." ?? For example, while it IS important to > update your system, I've actually been in situations where NOT being > updated has been a good thing. Certain vulnerabilities are found to > work in certain versions of certain applications, but earlier versions > (and sometimes later ones) may not necessarily be vulnerable. So how > would I emphasize that updating is important, but it's MORE important > that the user close off other vectors of attack (network penetration, > file system vulnerabilities, unmanaged users, etc.)? In many cases, "This is important," the concept, becomes "It is important to," the execution. The writer slides into passive voice without meaning to. (Guilty again, here.) I'm not advocating stating explicitly, "This section is important." Use an admonition to carry the sense of gravity. Here's an incomplete example of a good way to execute this intent, IMHO: <!-- DocBook XML snippet: <para> To properly secure your Internet-facing server, you <emphasis>must</emphasis> use <command>iptables</command>. The <command>iptables</command> facility within the kernel filters packets based on rules configured by the administrator. (Etc.) </para> <important> <title><command>iptables</command> configuration</title> <para> <emphasis>Always</emphasis> configure <command>iptables</command> for any &FC; server that faces the Internet. If you do not configure <command>iptables</command>, the default policy applies. The default policy is to accept any packet, which is inherently insecure. (Etc.) </para> </important> End of XML snippet. --> Note the admonition carries the weight of how important this section is. We don't need to hit the reader over the head, because the <important> admonition does it for us. Any reader who doesn't get the sense of importance from that admonition, and the use of an emphasized "must" in the previous paragraph, is simply not reading! :-) > > 8. When you direct readers, use correct words for the actions they > > should take. Users do not "go to" the Main Menu -> Foobar. They either > > click on Main Menu and then click on Foobar, or from the Main Menu they > > select Foobar. (I would argue the latter is better, because some people > > don't use a mouse even in the GUI. I actually avoid it depending on what > > I'm doing at the time.) > > I think this is a matter of semantics, and could just be a matter of > "learning the lingo". It's a matter of style, which should be consistent across tutorials, but yes, you're absolutely right. As you write more, read more of what's already produced, and try to match your style to the accepted standards, I suspect the usage will become second nature to you. > > 9. Avoid punctuation in your titles for sections or admonitions -- > > except for commas where demanded. ("Important!:", "Note:".) Instead, > > just use the title itself ("Important"). It is helpful (and encouraged) > > to use a title that says something about the admonition comment, such as > > "Stop services." This is a minor style point, but your editor will > > likely fix it if you don't. > > Again, a matter of nuance.... "Important!" reads as a lot more > important to me than "Important". This is also part of the style. Right now there's no "style chapter" in the Documentation Guide to tell you what's OK and what's not, so my advice here is not really criticism. It's more an attempt to give you a "heads up" of the issues that will be addressed in the style chapter. Writing that chapter is my responsibility, and I hope to have a first draft in a week or two. Nuance *is* important in professional technical writing, as anyone who does it for a living will tell you. It's part of what separates polished looking official documentation from the majority of what's available by Googling. > > 10. Avoid contractions when possible. They can be confusing to readers > > for whom English is not a first language. (Guilty) > > Generally a good practice. I am from the southeast, so it tends to come > a little too naturally sometimes. ;) I'm from Virginia, so I resemble that remark too! :-) [...snip...] > And all very valid points. I was going to say in my initial post (but > finally decided against it) that I have a hard shell for criticism, > since this is my first attempt at any sort of official documentation, > and really any technical writing, as well. I've written PLENTY of SOPs, > but the ones I write have to be designed for > Joe-Blow-I-Can't-Even-Spell-Linux types. They are also maintained with > a very limited audience scope, so I guess I'm allowed certain > "freedoms" (read: I'm the only one writing anything, so > standardization is pretty much what I say it is at this point [for MY > environment ;) ]). And that's all understandable. I've written in the past for my employer, but it was for similar purposes. I'm learning a lot from some of the pros who are here on this list, such as Mark, Tammy, and Karsten. For instance, when I wrote the advice in my last post, I was making a very conscious effort to write in an active voice. I didn't write "You probably don't want to do XYZ." Instead, I wrote "Avoid XYZ." The style in which I'm learning to write our documentation is carrying over into my writing on the list, to some extent. Unfortunately, it now takes me longer to write a list reply since I correct myself often! :-) I was particularly attentive to style here, partly because Karsten had just edited one of my documents. He provided a lot of advice on fitting my writing to a professionally acceptable style. I tend to drift when I "get on a roll," so to speak, and he picked up on that and didn't bother editing the whole document. It made more sense for him to do part of it, showing me what was wrong, and then leaving it up to me to fix the rest of it. I was also attentive to the style because my responsibility for the style chapter is starting to loom. I'm using examples from the tutorials I see, and write myself, for that purpose. In any case, there's *nothing wrong* with writing a first draft in which you don't worry about any of this. The previous advice just gives you an idea of how to revisit your document -- i.e. how to edit yourself on the second pass, which every writer should learn to do. The more self-editing you can do, the easier it will be for an editor to get your tutorial through the process later. And all other considerations aside, it's great that you are producing material. I hope other writers with your enthusiasm come out to help as well! -- Paul W. Frields, RHCE
