Red Hat Bugzilla – Bug 130978
New guide: Fedora Documentation Style Guide
Last modified: 2009-07-07 00:08:33 EDT
Description of problem: We need a Guide that will help writers and editors adhere to good style as they author and edit Fedora documentation. This guide would have its roots in standard English manuals of style, and is augmented by documents like the GNOME Documentation Style Guide (GDSG), which is also published under the GNU FDL. I would like to take the lead on this, so I am tracking this to the "ideas in progress" bug. Additional info: Current progress on the documentation, until the One True CVS is available, can be seen at the following URL's: XML source (ViewCVS of my SVN repository fedora-docs): http://svn.frields.org/ HTML build: http://docs.frields.org/ Subversion checkout: svn://svn.frields.org/fedora-docs/
I am starting out this work instead as a simple chapter addition to the existing Documentation Guide. I hope to have a draft chapter completed by Monday, September 20, 2004.
Created attachment 104810 [details] Patch to documentation-guide-en.xml Patch to top-level Documentation Guide XML source to add a <chapter> for Style Guidelines.
Created attachment 104812 [details] Style chapter for documentation-guide DocBook XML source for Style Guidelines chapter of Documentation Guide. This is not nearly what I hoped to have finished so far, and I realize it's behind schedule. That being said, I hope to have something done (finally!) by next week that will be usable. I'd love comments on the organization or input on any of the remarks I've made in the XML source.
Created attachment 105014 [details] New style chapter version with style tips This version has very minor revisions in the GDSG material, plus inclusion of the style tips I have been compiling. I think, as a whole, there's probably a good bit of redundancy in this chapter. I will work on reducing it and making it flow a little better.
Let's move forward with this. Decide what is the part you want me to edit, when you have it. I'll edit, patch the guide, and upload it. Are there particular pieces of this that come from the GNOME styleguide? Would pointers suffice? Does the GNOME source use any extra features or callouts in its license?
Sections 8.2 and 8.3 (those numbers are assigned if you apply the attached patch to documentation-guide-en.xml, import the new style chapter XML file, and build) are roughly verbatim from the GDSG. I've made only a few minor corrections thus far, but I'm not completely happy yet with the results. Some problems still hanging around include: * ugly use of <*table> for visual formatting, when the whole point of using DocBook is to avoid that very thing * repetition (the word "Rules:" goes against guidance in section 8.1, and is superfluous anyway) * some examples need to be formatted more in line with how we do coding * section 8.4 may need to be integrated rather than separate * section 8.4.3 needs to be retitled (just noticed this, sorry) Let me have a crack at it this weekend and run the results by you. (Yes, I know I've had this long to do it, but... well, y'know...) *sheepish grin* I'm moving this bug to NEEDINFO so it will nag me properly, since the ball is in my court, so to speak.
Created attachment 112626 [details] New style chapter with less redundancy Here's a better version, IMHO... The first section (general info) and the last section (composition tips) are the ones which I primarily wrote. The middle portion is almost entirely drawn from GDSG and EOS and may not need as much editorial attention.
Created attachment 112627 [details] New style chapter with less redundancy and cosmetic fixes Whoops, I sent the last one without having fixed a couple section headings. This one should be ready.
Ping! Also, I may have done something ugly to Bugzilla's normal workflow by switching the status to NEEDINFO against myself. I can't switch the status back to ASSIGNED; hopefully Karsten can do so. If you guys think this is a problem, perhaps I should bugzilla that against bugzilla.
Created attachment 113764 [details] Post-re-indenting grammatical and technical edit.
Created attachment 113765 [details] Post-re-indenting grammatical and technical edit.
Comment on attachment 113765 [details] Post-re-indenting grammatical and technical edit. Accidental resubmission of the patch.
This explains the patch just submitted, and covers the status of what is now in CVS. * Grabbed the latest tarball of docs-style-en.xml from svn.frields.org * Patched documentation-guide-en.xml to use the new chapter * Submitted these to CVS _prior_ to new indenting * Added local variable comment, re-indented, and committed this to CVS, making a massive diff that had zero content changes * Finished grammatical/technical edit, generated a patch with 'cvs diff -du', then committed the edits to CVS Using the patch attached to this bugzilla report will be easier than syncing just after the re-indenting but prior to the edits landing. I'm happy with this as-is for posting live and referring to. I'd like to see more stuff in the future, which any of us can write: * Examples in the Grammar and Usage Guidelines (negative and positive) * Look for more instances where the text breaks the rules it espouses Cheers!
This has been committed in CVS and published on f.r.c for some time, so I am closing this bug as CURRENTRELEASE. Any changes can come in as new bugs against the doc-guide-traqr.
Ticket moved to allow products to be removed from BZ.