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 ////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
Attachment:
signature.asc
Description: This is a digitally signed message part
-- fedora-docs-list mailing list fedora-docs-list@xxxxxxxxxx To unsubscribe: https://www.redhat.com/mailman/listinfo/fedora-docs-list
