Hey,
I don't know but I'm guessing this was prompted by the Revisor doc?
I'll quickly add that with the Revisor doc, the unity team were
looking for something to be included with the RPM, so I guess a more
descriptive tone would be appropriate here?
Perhaps a set of docs that are more how-to in nature can be created
from the doc I've started now? I'd be happy to do them at some point.
Lol - saying that, had you not pointed it out it's something I'd
probably never have considered (so it was certainly not an intentional
choice for this doc!!) and I think it's something I've done elsewhere,
so it's good to know and I hope I improve it in my writing :D
Cheers,
Jon
On 07/06/07, Karsten Wade <kwade@xxxxxxxxxx> wrote:
Just a general note, because it happens to all of us, and it is always
worth mentioning.
When writing technical docs, it is easy to slip into a descriptive mode,
where we:
* List what is on the screen and what happens when you click it
* List all the commands available and what some combinations do
(examples)
What we forget is that much of that is available by reading the help
docs or the man/info pages. All that content is actually "what is"
information. Docs written to that spec are like maps, guiding you to a
location, but not telling what you can do once you get there.
How-to/what-you-can-do documents are different. They focus on one or
more specific tasks the user wants to accomplish:
* Setting up a home firewall to supplement or replace an appliance
* Hardening a system beyond the defaults
* Programming a Python application that interacts with a Web service
* Creating a custom live spin of Fedora
Honestly, those documents assume the existence of the other content --
the help/man/info pages.
We want to keep our content focused on what hasn't been written. Focus
on specific examples, tasks the reader wants to accomplish. Make them
specific enough *and* generic enough, so they can be applied to
different situations.
When working, read all the associated documents that come e.g. with the
RPM package (/usr/share/doc/foo). If those are lacking, make notes
about what needs to be added. Keep adding to those notes as you write
your how-to-do-it, noting what needs to be added to the default content
to make it (more) complete.
This summer, there is a student project[1] that is working to provide a
Wiki-based front end to editing man and info pages. A goal is to
produce patches that can be submitted upstream, probably through
bugzilla. This is going to give you somewhere to input all those good
ideas you've been saving.
Then we can reference the default package docs from within our
supplemental docs, relying upon them to be complete and useful.
- Karsten
[1] http://fedoraproject.org/wiki/SummerOfCode/2007/VillePekkaVainio
More is coming from Ville-Pekka on this.
--
Karsten Wade, 108 Editor ^ Fedora Documentation Project
Sr. Developer Relations Mgr. | fedoraproject.org/wiki/DocsProject
quaid.108.redhat.com | gpg key: AD0E0C41
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
--
fedora-docs-list mailing list
fedora-docs-list@xxxxxxxxxx
To unsubscribe:
https://www.redhat.com/mailman/listinfo/fedora-docs-list
--
fedora-docs-list mailing list
fedora-docs-list@xxxxxxxxxx
To unsubscribe:
https://www.redhat.com/mailman/listinfo/fedora-docs-list
