Bug 130978 - New guide: Fedora Documentation Style Guide
New guide: Fedora Documentation Style Guide
Status: CLOSED CURRENTRELEASE
Product: Fedora Documentation
Classification: Fedora
Component: docs-requests (Show other bugs)
devel
All Linux
medium Severity medium
: ---
: ---
Assigned To: Karsten Wade
Tammy Fox
http://www.redhat.com/archives/fedora...
: FutureFeature
Depends On:
Blocks: fedora-docs-writing
  Show dependency treegraph
 
Reported: 2004-08-26 09:49 EDT by Paul W. Frields
Modified: 2009-07-07 00:08 EDT (History)
1 user (show)

See Also:
Fixed In Version:
Doc Type: Enhancement
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2005-06-24 16:14:47 EDT
Type: ---
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)
Patch to documentation-guide-en.xml (576 bytes, patch)
2004-10-05 17:50 EDT, Paul W. Frields
no flags Details | Diff
Style chapter for documentation-guide (8.23 KB, text/plain)
2004-10-05 17:52 EDT, Paul W. Frields
no flags Details
New style chapter version with style tips (76.83 KB, text/plain)
2004-10-11 11:15 EDT, Paul W. Frields
no flags Details
New style chapter with less redundancy (53.24 KB, text/plain)
2005-04-02 15:01 EST, Paul W. Frields
no flags Details
New style chapter with less redundancy and cosmetic fixes (53.24 KB, text/plain)
2005-04-02 15:09 EST, Paul W. Frields
no flags Details
Post-re-indenting grammatical and technical edit. (21.20 KB, patch)
2005-04-28 06:31 EDT, Karsten Wade
no flags Details | Diff
Post-re-indenting grammatical and technical edit. (21.20 KB, patch)
2005-04-28 06:33 EDT, Karsten Wade
no flags Details | Diff

  None (edit)
Description Paul W. Frields 2004-08-26 09:49:11 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/
Comment 1 Paul W. Frields 2004-09-13 17:13:21 EDT
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.
Comment 2 Paul W. Frields 2004-10-05 17:50:02 EDT
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.
Comment 3 Paul W. Frields 2004-10-05 17:52:06 EDT
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.
Comment 4 Paul W. Frields 2004-10-11 11:15:57 EDT
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.
Comment 5 Karsten Wade 2005-04-01 15:56:27 EST
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?
Comment 6 Paul W. Frields 2005-04-01 20:47:17 EST
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.
Comment 7 Paul W. Frields 2005-04-02 15:01:13 EST
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.
Comment 8 Paul W. Frields 2005-04-02 15:09:37 EST
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.
Comment 9 Paul W. Frields 2005-04-08 09:20:42 EDT
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.
Comment 10 Karsten Wade 2005-04-28 06:31:53 EDT
Created attachment 113764 [details]
Post-re-indenting grammatical and technical edit.
Comment 11 Karsten Wade 2005-04-28 06:33:20 EDT
Created attachment 113765 [details]
Post-re-indenting grammatical and technical edit.
Comment 12 Karsten Wade 2005-04-28 06:34:04 EDT
Comment on attachment 113765 [details]
Post-re-indenting grammatical and technical edit.

Accidental resubmission of the patch.
Comment 13 Karsten Wade 2005-04-28 06:39:59 EDT
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!
Comment 14 Paul W. Frields 2005-06-24 16:14:47 EDT
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.
Comment 15 eric@christensenplace.us 2009-07-07 00:08:33 EDT
Ticket moved to allow products to be removed from BZ.

Note You need to log in before you can comment on or make changes to this bug.