what is v. how to

Jonathan Roberts jonathan.roberts.uk at googlemail.com
Thu Jun 7 08:33:26 UTC 2007


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 at redhat.com> 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 at redhat.com
> To unsubscribe:
> https://www.redhat.com/mailman/listinfo/fedora-docs-list
>
>




More information about the fedora-docs-list mailing list