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
