cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <rgard...@apache.org>
Subject Re: [docs] regenerated website; why extra docs?
Date Wed, 15 Feb 2006 14:36:30 GMT
hepabolu wrote:
> David Crossley wrote:
> 
>> Today i re-generated the cocoon.apache.org/2.1/ website
>> which incorporates a few changes to the Daisy sources,
>> fixes some links that used local hrefs, removes the
>> old ApacheCon logo.
>>
>> There were some new documents generated which do not
>> have any mapping in the navigation. Does someone know
>> what should happen with them? ...
>>

They will be linked from another page and thus find their way into the docs.

You can check what is linking to a document by visiting the page in 
Daisy and clicking the "referers" link on the right.

For example, the first in your list (doc 372) is referred to by doc 611 
(which is 
http://cocoon.zones.apache.org/daisy/legacydocs/documentation/developing/concepts/httprequest.html

which is referenced in the navigation).

Interestingly this document (372) is actually an image and therefore 
should not be linked to like this but embedded as an image.

How does Forrest render this document? I didn't (knowingly) handle 
non-embedded image files in the Forrest plugin. We may need to add some 
special handling for this.

...

> New documentation for new releases should go into the "official 
> documentation". However, nobody has decided yet on a structure for that 
> collection nor for the subsequent structure of the navigation as it goes 
> onto cocoon.apache.org.
> 
> So I suggest that for now you ignore the newly created files when 
> website is re-generated.

No, this is not possible. Remember we are building the Forrest site 
structure from those defined in Daisy. To "ignore" some of the daisy 
files like this we will need to define a separate Forrest site 
structure. This is possible but we decided against it when creating the 
site.

What I think we should be doing is creating a new version of the 
documentation, just as we do with code.

> Someone (me, the authors, or someone else) has to go through these 
> files, and decide on the following:
> 
> 1. do they describe something that is part of the next upcoming 2.1.X 
> release?
> - Yes: add them to the navigation menu in the "legacy documentation" at 
> an appropriate place and give them a "name" in that menu.

This is not always appropriate. The above example, in which a new 
document is an image file is one such example. Furthermore, this assumes 
that al documents should appear in the navigation menu, which I do not 
believe is the case. We need to be making the main nav menu smaller and 
less confusing, not larger.

Better to create a new version of the docs for 2.1.9

> 3. are they random thoughts, wild ideas, parking places for unfinished 
> things?
> - Yes: mark them as such, they should not be exported as documentation
> - No: should it really be there? Can't it be deleted?

There should be another collection for such "scratchpad" work. We can 
easily move stuff out of the scratchpad and into an "offical" collection.

> That leaves us with the decision on the navigation structure of the 
> 2.2/3.0 documentation. It was already decided that the navigation in 
> Daisy should be targeted towards editors (i.e. simplify their work), 
> while the "official" navigation could be entirely different. Maybe we 
> should use the Daisy books definition for the navigation structure of 
> the website to take advantage of the query-based navigation 
> possibilities (or are they not present in books definitions?).

Use the books structure for what it is intended for - printed books.

Use the daisy navigation structure for what it is best for - web sites.

You can have different navigation menus for different purposes, i.e. one 
for editos, used in Daisy, one for users, used for the user focussed 
portion of the web site, one for devs, for the dev portion of the web 
site, etc.

Query based nacigation is possible in normal navigation menus as well as 
book's.

When I find the time to put the FAQ documents together you will see an 
example of what I mean.

Ross

Mime
View raw message