[wp-docs] Intro

[Mark Styles]

On Mon, Dec 11, 2006 at 11:21:02PM +1300, Matthew Paul Thomas wrote:
> On Dec 6, 2006, at 2:00 PM, Mark Styles wrote:
> >On Tue, Dec 05, 2006 at 12:50:02PM -0800, Matt Mullenweg wrote:
> >>What are your thoughts on the current organization of the 
> >>documentation and how it could be improved?
> >
> >I like the idea of starting with a book metaphor and expanding from
> >that. Defining a small set of "chapters" and an even smaller set of
> >"appendices" and assigning all content to one chapter or appendix.
> >Hyperlinking within the content will still let people jump around
> >wherever they want but there would be an underlying start to finish
> >organisation.
> >...
> 
> Ironically, in Ubuntu we're (slowly) moving in the opposite direction 
> -- fewer book-style manuals and guides with chapters, and more 
> individual pages on specific topics. 
> <https://wiki.ubuntu.com/TopicBasedHelp> Similar will eventually happen 
> for the Gnome system on which Ubuntu is based.

I don't think the two options are mutually exclusive. It's a good idea
to have small individual pages on individual topics, but those
individual pages should also be organised into some kind of book/chapter
format.

I find a lot of the codex pages too long and too wordy, but striking a
good balance between conciseness and good explanations is a tricky
balancing act and depends a lot on your target audience.

-- 
Mark 
http://www.lambic.co.uk

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://comox.textdrive.com/pipermail/wp-docs/attachments/20061215/b27731fe/attachment.pgp