what is v. how to

[Karsten Wade]

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
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20070606/13fbbfa5/attachment.sig>