Hi Paul,
Your brain dump is chock full of useful suggestions, esp regarding the content of a "Getting Started writng Docs for Fedora", or whatever the document name turns out to be.
I hope you don't mind if I "appropriate" some of your ideas into the fedora-docs tutorial:-)
Thanks, Mark
Paul W. Frields wrote:
The following is a core dump, because I have to get to a HOA meeting and want to strike while the iron is hot. (Why yes, that *does* mean I have a thick head, thanks for noticing.)
Ideas for improvied Docs Guide organization:
"Part 0." Which part you should start reading. If you skip any parts (e.g. you already have a tutorial written), what do you need to know to proceed?
Part 1. From idea to assignment. Guidelines for scope, "pitch" (sorry if it's too Hollywood -- I mean defining the syllabus or synopsis), and how to get the FDP's attention (where to find us, come with a project in mind if possible, etc.). Why this is a good idea rather than just throwing documents at us pell-mell. Querying BZ for ideas.
Part 2. From assignment to production. A slightly gentler how-to on getting the tools working, especially for
the Emacs/PSGML faint-of-heart. Pointers to other tool sets, and maybe
even instructions as well. Guidelines for the system you're documenting,
such as making sure that you're eliminating variables on your system to
which the "average" Fedora user isn't privy, trying to stick to best
methods for doing things (up2date vs. cli apt/yum, RPM vs tarballs,
etc.). Remember that we are not here to "fix" the system, we are here to
document how to use it as is. (See GNOME Docs Guide for similar
sentiments.)
We might want to include a style guide here.
Part 3. From production to posting. How to submit the finished sources (BZ, eventual CVS,
fedora-docs-list...). What happens to your document after you submit it.
What the editor's responsibility is to you. What your responsibility is
to the editor. Approval process.
Part 4. From posting to...? (the grave?) FDP/editors'/authors' responsibilities for keeping docs updated, and how to change hands. Using BZ to report or query problems. Resolving problems. Branching documents for different releases of FC.
Just some thoughts, more to come I fear.... :-)
-- ---------------------------------------------------------- Mark Johnson <mjohnson@xxxxxxxxxx> Red Hat Documentation Group <http://www.redhat.com> Tel: 919.754.4151 Fax: 919.754.3708 GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242
