Style chapter for documentation-guide
The first draft (*very* rough) is available in the Bugzilla entry for
this topic:
http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=130978
Also available in the bug is a patch for the documentation-guide-en.xml
file to include the new docs-style-en.xml file in a build. Drawbacks I
already recognize:
- It is redundant in spots. In others, it is redundant as well.
I purposely added in my ever-expanding "tips" section without regard to
their duplicating material imported from the GDSG. I will whittle away
at this problem, but am still looking for additional tips, "gotchas,"
and advice to both new and practiced writers.
- It creates additional editing needs on the overall Docs Guide.
Most importantly, front matter needs to be added to take care of GNU
FDL requirements, since I am building off the GDSG. I haven't done this
before and would appreciate assistance from someone who has.
- The organizational structure may be confusing.
If you have comments or suggestions, they're always appreciated.
Originally my thoughts were that the structure would be something like
this:
1. What style means and why it's important
2. General guide to writing technical docs
3. Grammar rules
4. Composition rules
5. Style FAQ (tips, etc.)
Thanks in advance for your input, and I hope everyone has docs ideas
percolating out there. :-) Cheers to all!
--
Paul W. Frields, RHCE