editors

Paul W. Frields paul at frields.com
Fri Aug 13 12:03:03 UTC 2004


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





More information about the fedora-docs-list mailing list