Messages in this thread | | | Date | Tue, 22 Nov 2005 08:46:55 -0500 (EST) | From | Steven Rostedt <> | Subject | Re: [RFC] Documentation dir is a mess |
| |
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@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
| |