what next?

[Dimitris Glezos]

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 at jabber.org, PGP: 0xA5A04C3B
http://dimitris.glezos.com/

"He who gives up functionality for ease of use
loses both and deserves neither." (Anonymous)
--