Now that the release candidate is done, all of you have a chance to
check it out and voice your opinions while I am going to be quiet for
a couple of days doing some other work and going kayaking until the
weekend.
Before I do, I want to say a huge thank you to David for tirelessly
(to be taken literally) working with me on the restructuring when he
had other things to do and mopping up my many mistakes.
I think we both learned a lot about Forrest and working together over
the Internet which I will try to document next week.
I also wanted to say that although we think this system is a huge step
forward, it is in no way meant to be static or final and encourage a
debate in making it even better.
Let me start with a few steps on my agenda:
- I will write a document explaining the details of how the
documentation structure is meant to work and howtos on inserting
new information and create new releases.
- The structure of menu items in the versions docs tabs is going to be
refined to group things more clearly. If I find the time will I try to
do this until Wednesday this week so that it can still be part of
the new release.
- To keep things simple we have started out by making a lot of
documentation 'versioned' thus increasing the volume of our
site-author-directory quite a bit.
In the upcoming weeks I'd like to go through the documentation and
move items like the dtd-documentation back into a directory 'docs'
since there is no need for versioning these with Forrest releases.
This will mean no visible change to the user interface as the
documents will still show under versioned docs (because they may or
may not be available in one specific version) but it means that
both versions will link to the same file.
- Going through the documentation I found a couple more special cases
such as
= old dtds that are no longer required for active versions
(document-v11 and -v12) but might still be wanted on special
occasions. I'm thinking about having a separate folder or folders
for these where we move them as a first step of their retirement
while still keeping them linked before gradually throwing them out
alltogether.
Having them in a separate directory makes it easy for people to
signal their intent of retiring them in the future (by moving them
there) and allow us to check and clean the folder before each
release. Deleting a file from here will still be a case-ba-case
descision of course.
= Liste of changes: This is an unsolved issue that we will need to
solve before the release. I'd like to move them up to the project
level as it has all changes of all versions and doesn't really
belong in 'versioned docs' but if somebody wants to make the
effort we could also have a filtered version of just the changes
in 0.6, 0.7 and so on linked into the versioned docs part.
= We might eventually admit to having some non-versioned Forrest
docs and show them as a separate Tab. But I don't like this idea
because I prefer to have all documentation items on a version
to be in one menu (so that newbies can find and read all docs by
going through one menu).
A possible solution might be to utilize Davids great new MOTD hack
and imprint a different message to docs that reside in the non
versioned docs-folder.
So a dtd-documentation residing in docs would show in the
versioned docs menu but when you open it have a MOTD saying 'This
is non-versioned documentation that applies to more than one
version of Forrest'.
Adding an 'applies to'-information at the top of the document
would in my eyes make this complete.
OK, so much to get us started on this. Looking forward to your
comments. To facilitate a more structured discussion I will append an
separate response for each of the ideas for further discussion.
--
Ferdinand Soethe
