forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ferdinand Soethe <samm...@soethe.net>
Subject New documentation structure, next steps
Date Tue, 14 Jun 2005 08:51:19 GMT

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


Mime
View raw message