On Fri, 2004-08-13 at 04:18, Dave Pawson wrote: > > Good points, these. For example, the Samba/LDAP tutorial needs someone > > who works in a more mixed environment. I don't have any systems at work > > that are running Windows with which to test this stuff. > > I'm running both, two side by side machines? FC2 and win2k. > I've got samba running, but not set up right I guess, since its not > an easy flow of files between the two. > What's needed Paul? Hi Dave, What's required is (1) a check of the technical accuracy of the document, and (2) rewriting to eliminate problems of style. As I mentioned, I don't have any Windows boxes with which to check some of the technical fine points, nor am I that familiar with LDAP (soon, but not right now). I can do the style rewriting, but you had mentioned you were interested in doing so yourself, and I would like to spend the time working on the Style Guide. I know that sounds a little backward, but if you know good technical documentation, you probably can see the problems in the doc and how to fix them without a formal Style Guide. (For example, "OK, let's get started!" and "We'll do XYZ..." are clearly out of place, even if they have a nice, friendly ring.) The fine points could always be tweaked later. If you (or anyone on the list) is interested in doing the technical evaluation, I would suggest the following guidelines (I'll be general so that this might be useful to someone for another doc): Once you've completed whatever portion you're willing to massage, just drop a patch to the XML in Bugzilla under the doc's entry there (#129739). 1. Goals - The document might lay out a number of scenarios, with each one requiring an alteration in the steps, but in which the goals are related. Test the document using each major scenario presented. Does it work as written? Are there sections that are unclear, misleading, or out of date? 2. Common Failures - Does the document address possible causes of failure? In other words, if things didn't work right and you followed all the steps correctly, would it be within the doc's scope to tell you what might be wrong? Every document shouldn't turn into a full-fledged troubleshooting class, but if there is a common point of failure, a short note is probably required. 3. Other Omissions - Is there something the document didn't address, about which you have questions when you're running it, and which you think other people are likely to have? If anyone sees problems with these guidelines, or I've missed or skipped something obvious, please chime in. I am also cc'ing this to the original author, on the off chance that he might be interested in participating. -- Paul W. Frields, RHCE
