what is v. how to
kwade at redhat.com
Thu Jun 7 02:39:56 UTC 2007
Just a general note, because it happens to all of us, and it is always
When writing technical docs, it is easy to slip into a descriptive mode,
* List what is on the screen and what happens when you click it
* List all the commands available and what some combinations do
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
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 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.
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
-------------- next part --------------
A non-text attachment was scrubbed...
Size: 189 bytes
Desc: This is a digitally signed message part
More information about the fedora-docs-list