cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From hepabolu <hepab...@gmail.com>
Subject Re: [docs] test publish from daisy
Date Wed, 12 Oct 2005 12:01:10 GMT
Ross Gardler wrote:
> See: http://people.apache.org/~rgardler/cocoon-site/653.daisy.html

Correct. It looks much slicker than the "official" site, although my 
fingers itch to do something about the navigation (CSS wise).

> There are broken links now we switched to the new navigation. See 
> http://people.apache.org/~rgardler/cocoon-site/brokenlinks.xml

Hmm, I've looked this page but there are quite a few odd broken links.
Looking into this:

- page 417 is actually wrong in its source, i.e. the links are wrong in 
the original xdoc version as well. Since it's more or less outdated I'm 
not really interested in updating it.
The same goes for other pages.

- page 654 should be excluded from the export, since it has only 
relevance in Daisy and does not contain any Cocoon related information.

- the reference to index.xml/index.html I cannot explain. Have you 
looked at the nodeID attribute of each doc in the navigation file? I've 
entered the "original" filename to avoid the numbering in the URL as 
well as give some "backward compatibility".

> It is worth noting that you can break up the navigation into multiple 
> documents within Diasy and then bring them together into a single site 
> structure for Forrest. This makes it a little easier on the Daisy side 
> of things since you only see nav elements of interest to your current 
> focus.

Well, I've done this for the legacydocs to get everything in one place 
and to have "backward compatibility".

Now that Daisy books are available, things have changed. I've discussed 
this with the guys from Outerthought and actually we feel that the Daisy 
navigation should be geared towards the editors. So there should be 
queries like "my documents", "legacy documents not yet decided on", "all 
documents A-Z". In any case, adding a new page should not mean you have 
to manually edit the navigation file.

The navigation for Daisy books should be geared towards the reader/user 
and would follow the current navigation much more. We might even end up 
with several Daisy books (e.g. User Manual, Reference Guide).

> For example, we can have a nav document for User Docs, Dev Docs, 
> Overview, Live sites etc. Each of these sections could be given a tab 
> for easy navigation and can form the basis of a "daisy book".

As you see above, it should be the other way around.

> Would you like me to illustrate this by splitting the user and dev doc 
> navigation files out?

I get the idea, but I think it is not worth the effort. The legacy docs 
are there as an effort to consolidate all CURRENT documentation and 
provide the best quality of documentation we currently have. I'll finish 
my project of removing docs from the repository ASAP, to avoid further 
confusion of where to modify/add documentation.

 From then on, we should focus on improving the information in the 
"Cocoon Documentation" collection/site. The legacydocs then only serve 
as a "pool of information": if what you want to write about is already 
in the legacydocs, update it and move it from the legacydocs collection 
to the documentation collection.
If you find really outdated documents in the legacydocs, you can mark 
them "retired" and they will "disappear" from the navigation.

> I've turned PDF's off for now. Currently the Forrest plugin does not 
> support Daisy Books, but it should. In the meantime we can pull the 
> published book from Daisy. This is not a problem as long as we are not 
> trying to integrate content from different sources into the book (which 
> at present we are not doing).

No, I don't think integration is necessary. As stated in a previous post 
I'm thinking about a few relatively static pages with the most prominent 
info on Cocoon and a link to the Daisy book(s) for the actual documentation.

Since Cocoon 2.2-dev switched to Maven2 for the build I figured we might 
as well use a part of the site building functionality in Maven.
I'm currently filling in the blanks for the "project info" and some of 
the "project reports", i.e. only the info that is part of the main pom.xml.
That will give enough information to users and potential contributers to 
get up and running and after that there's the Daisy documentation.

This information is almost static and answers a lot of the FAQs I've 
seen lately (i.e. SVN address, mailing lists etc.).

Of course, skinning should be done as well.

WDYT?

Bye, Helma




Mime
View raw message