Karsten Wade wrote:
On Tue, 2006-11-07 at 14:46 +0000, Dimitris Glezos wrote:
I think it would be better to avoid having too much information in
FAQ-style, since although referencable, they are not very readable or
usable as a manual.
On the other hand, it would be great if we had that information in the
guides/chapters and compile a set of FAQ that the answer is like "More
information for this can be found <there>. For customizing it, see
Chapter <Foo>, paragraph <Bar>".
Right, we have to have a process that integrates the two properly.
Regardless of our individual preferences, knowledgebase-style content is
very popular and useful.
I believe we can do that. We just have to start designing and agreeing
on a good hierarchy for our handbook and build on top of that. Oh, and
of course, decide what our audience will be. :)
> We might be able to think of this as part of the modularizing of
> content. That is, can we write content in such a way that it is both
> useful in a kbase and fits into an overall document? Perhaps, perhaps
> not.
One definite goal of our should be to *converge* the places/ways we
maintain content and minimize the same-content-different-location
issues. Try to move as much informally-written content as possible from
the wiki to the guides/handbook.
The difficult part would be to strike a good balance for this. Ie, we
want to minimize duplicate content but at the same time we want the
Release notes to contain installation notes that should exist in the
Installation Guide. Modularization implies maintainability but also
dependencies and we will have to make some choices for the places where
we will duplicate content instead of referencing.
I believe the most difficult part of doing the Handbook would be to
decide on a good hierarchy that strikes a good balance between
usability/quality and reference-able.
Yes, and we might want to strike toward the former and let other works
do the latter, which is where formal (kbase) and informal (forums, etc.)
fit in.
+1. The kbase's aim should be to serve as reference the content of our
documentation (something like a FAQ).
...
http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/step-guide/
Who should we contact to move some strings to free those docs? It would
be *great* if we could use them.
We[1] called in Max Spevack some months ago to help make this happen,
since I wasn't able to get it completed myself. Anyone who wants to
lend support to this idea, please email Max directly with a personal
plea, useful cases, etc.; he agrees with us, but it is helpful to know
exactly what the community wants when we are discussing schedules with
RHEL team members.
I guess we'll know what we really need when we agree on the structure of
our big doc.
If everyone is OK with the idea, I'll try to bootstrap a tree structure
based on other guides (like the excellent FreeBSD cookbook) and put it
on the wiki for further discussion. Thankfully, most of the big parts
are already there (IG, DUG, FAQ).
-d
--
Dimitris Glezos
Jabber ID: glezos@xxxxxxxxxx, PGP: 0xA5A04C3B
http://dimitris.glezos.com/
"He who gives up functionality for ease of use
loses both and deserves neither." (Anonymous)
--
--
fedora-docs-list mailing list
fedora-docs-list@xxxxxxxxxx
To unsubscribe:
https://www.redhat.com/mailman/listinfo/fedora-docs-list
