Re: [RFC] Documentation dir is a mess

[Steven Rostedt]

On Tue, 22 Nov 2005, Paul Jackson wrote:

> > The documents
> > that exist may not conform themselves well to that sort of division,
> > necessarily.
>
> Good point, not just for -that- sort of division, but perhaps for
> any sort.
>
> I am skeptical that there is much value to be added to the current
> hodge podge of documents in the Documentation directory by rearranging
> them in some grand scheme.
>
> Certainly there is some value that can be subtracted -- just changing
> it will result in some minor cost to each of us, adjusting to the
> changes.  The greater the changes, the more aggressive the effort to
> categorize it, the greater this distributed cost of change.
>
> Perhaps what we have is deeper than just improperly arranged Docs.
> The content of the Docs may have too much variation in depth, topic,
> breadth, organization, style and such to be well suited to a deep
> structure.
>
> Maybe it looks disorganized because it is -- more than just skin deep.
>

Exactly why the documents _should_ be rearranged.  If you expect the
contents of the documents to be cleaned up first, that wont happen. But if
you make an hierarchy out of the current Document design (which there is
some attempt to do so already there), then later changes can be to start
breaking up the documents that have too much at every level into smaller
versions where they belong.

So the hierarchy can be like an outline. The first stab at this should
just be to make the catagories that are needed, and still allow those
catagories themselves be able to change.  Then, if necessary, modify the
documents.

This would need to be done in a step by step basis.  Although the first
round can be the creation of the document directories with the attempt of
placing every document in the toplevel Document directory into a lower
directory.  Then we can slowly start fixing them one by one.

Like I said, I would be willing to start reading each document and see
where it might fit.  You may not agree with my decision, but then we can
discuss it and find a proper fit.

So the question remains, how does one start this?  Should someone just
take a crack at it, submit it, and then let the games begin?

-- Steve

-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/