Bug 130978 - New guide: Fedora Documentation Style Guide
Summary: New guide: Fedora Documentation Style Guide
Keywords:
Status: CLOSED CURRENTRELEASE
Alias: None
Product: Fedora Documentation
Classification: Retired
Component: docs-requests
Version: devel
Hardware: All
OS: Linux
medium
medium
Target Milestone: ---
Assignee: Karsten Wade
QA Contact: Tammy Fox
URL: http://www.redhat.com/archives/fedora...
Whiteboard:
Depends On:
Blocks: fedora-docs-writing
TreeView+ depends on / blocked
 
Reported: 2004-08-26 13:49 UTC by Paul W. Frields
Modified: 2009-07-07 04:08 UTC (History)
1 user (show)

Fixed In Version:
Clone Of:
Environment:
Last Closed: 2005-06-24 20:14:47 UTC
Embargoed:


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

Description Paul W. Frields 2004-08-26 13:49:11 UTC
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 21:13:21 UTC
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 21:50:02 UTC
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 21:52:06 UTC
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 15:15:57 UTC
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 20:56:27 UTC
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-02 01:47:17 UTC
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 20:01:13 UTC
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 20:09:37 UTC
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 13:20:42 UTC
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 10:31:53 UTC
Created attachment 113764 [details]
Post-re-indenting grammatical and technical edit.

Comment 11 Karsten Wade 2005-04-28 10:33:20 UTC
Created attachment 113765 [details]
Post-re-indenting grammatical and technical edit.

Comment 12 Karsten Wade 2005-04-28 10:34:04 UTC
Comment on attachment 113765 [details]
Post-re-indenting grammatical and technical edit.

Accidental resubmission of the patch.

Comment 13 Karsten Wade 2005-04-28 10:39:59 UTC
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 20:14:47 UTC
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 2009-07-07 04:08:33 UTC
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.