how can I help?

[John J. McDonough]

----- Original Message ----- 
From: "Adam Williamson" <awilliam at redhat.com>
To: "For participants of the Documentation Project" 
<fedora-docs-list at redhat.com>
Sent: Monday, July 20, 2009 7:07 PM
Subject: Re: how can I help?


The problem with the XML docs is that they are imposing.  The problem with 
the wiki is that you can't find anything.  And find means not only the user 
finding things, but the maintainers.

The one thing that I *can* find on the wiki is the release notes beat pages, 
and that is only because I know where the index is.  Most of the other pages 
have nothing pointing to them, so you can only find a page by sheer dumb 
luck.  We had hoped to make the search function useable by renaming the 
pages, but that doesn't seem to have succeeded, and we lost the ability to 
navigate a tree in the attempt.

I wonder whether the release notes model isn't a good one for the other 
docs?  That is, write the doc in the wiki, and then nearing release convert 
it to xml.  With some sort of table of contents pages, the data might 
actually be findable.

The wiki offers us something else that the XML does not; pages can be 
organized in multiple ways.  We could, for example, have a page that 
describes writing a letter in OO.  This could be pointed to by the "task" 
table of contents "how to write a letter" as well as by the Open Office 
table of contents, using OOWriter..  if the individual pages were somewhat 
atomic, we might find that some fragments of content could be used in more 
than one document.

Just some rambling.

--McD