You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by Ferdinand Soethe <sa...@soethe.net> on 2005/06/14 10:51:19 UTC
New documentation structure, next steps
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
Refining the structure of docs-menus (Re: New documentation structure, next steps)
Posted by Ferdinand Soethe <sa...@soethe.net>.
> - 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.
Re: Retirement of docs (Re: New documentation structure, next steps)
Posted by Cyriaque Dupoirieux <Cy...@pcotech.fr>.
Juan Jose Pablos a écrit :
> Cyriaque Dupoirieux wrote:
>
>>
>> Just want to add that some dtdV1todtdV2.xsl files already exist in
>> $FORREST_HOME/main/webapp/resources/stylesheets.
>> It could be a good idea to maintain these kind of files in order to
>> migrate old forrest site...
>>
>> For instance, we recently change the skinconf.xsl from v6-3 to v7 and
>> the motd declaration is completly different.
>> A skinconfv63tosxkinconfv70.xsl would have been welcome.
>>
>> WDYT ?
>>
>
> Have a look on main/webapp/resources/stylesheets/upgrade-skinconf.xsl
> it was done for the 0.51 --> 0.6 so I guess that we could use it for
> 0.7 as well...
>
Okay, that's it I suppose.
It is used in site.xml to automatically upgrade the skinconf.xml before
to use it.
I continue to think that this behaviour is interesting and should be
generalized to any DTD - Changes, document, todo...
Cyriaque,
Re: Retirement of docs (Re: New documentation structure, next steps)
Posted by Juan Jose Pablos <ch...@apache.org>.
Cyriaque Dupoirieux wrote:
>
> Just want to add that some dtdV1todtdV2.xsl files already exist in
> $FORREST_HOME/main/webapp/resources/stylesheets.
> It could be a good idea to maintain these kind of files in order to
> migrate old forrest site...
>
> For instance, we recently change the skinconf.xsl from v6-3 to v7 and
> the motd declaration is completly different.
> A skinconfv63tosxkinconfv70.xsl would have been welcome.
>
> WDYT ?
>
Have a look on main/webapp/resources/stylesheets/upgrade-skinconf.xsl
it was done for the 0.51 --> 0.6 so I guess that we could use it for 0.7
as well...
Re: Retirement of docs (Re: New documentation structure, next steps)
Posted by Cyriaque Dupoirieux <Cy...@pcotech.fr>.
Just want to add that some dtdV1todtdV2.xsl files already exist in
$FORREST_HOME/main/webapp/resources/stylesheets.
It could be a good idea to maintain these kind of files in order to
migrate old forrest site...
For instance, we recently change the skinconf.xsl from v6-3 to v7 and
the motd declaration is completly different.
A skinconfv63tosxkinconfv70.xsl would have been welcome.
WDYT ?
Cyriaque,
Ferdinand Soethe a écrit :
>Ross Gardler wrote:
>
>
>
>>It is a good idea to clearly mark deprecated DTD's. In fact I would go a
>>step further and say we move them to a deprecatedDTD plugin. This would
>>be an internal plugin. This would leave only active DTD's in core so new
>>users will not be tempted to use deprecated ones.
>>
>>
>
>Certainly worth consideration.
>
>
>
>>However, it is not as simple as it may sound. For example, document1.3
>>extends document 1.2 which extends document 1.1, therefore for document
>>1.3 we need all earlier versions. It would therefore seem that the first
>>step would be to do as you propose, move the earlier DTD's into a
>>deprecated folder and think about the next step later.
>>
>>
>
>Yes, I figured that we have more important issues to program so I took
>a simple solution. Besides, this solution would be more general and
>could also be applied to old howtos such as the one on CVS-SSH.
>(Although we could donate that to projects still using CVS :-))
>
>
>
>--
>Ferdinand Soethe
>
>
>
>
Re: Retirement of docs (Re: New documentation structure, next steps)
Posted by Ferdinand Soethe <sa...@soethe.net>.
Ross Gardler wrote:
> It is a good idea to clearly mark deprecated DTD's. In fact I would go a
> step further and say we move them to a deprecatedDTD plugin. This would
> be an internal plugin. This would leave only active DTD's in core so new
> users will not be tempted to use deprecated ones.
Certainly worth consideration.
> However, it is not as simple as it may sound. For example, document1.3
> extends document 1.2 which extends document 1.1, therefore for document
> 1.3 we need all earlier versions. It would therefore seem that the first
> step would be to do as you propose, move the earlier DTD's into a
> deprecated folder and think about the next step later.
Yes, I figured that we have more important issues to program so I took
a simple solution. Besides, this solution would be more general and
could also be applied to old howtos such as the one on CVS-SSH.
(Although we could donate that to projects still using CVS :-))
--
Ferdinand Soethe
Re: Retirement of docs (Re: New documentation structure, next steps)
Posted by Ross Gardler <rg...@apache.org>.
Ferdinand Soethe wrote:
>
>>= 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.
It is a good idea to clearly mark deprecated DTD's. In fact I would go a
step further and say we move them to a deprecatedDTD plugin. This would
be an internal plugin. This would leave only active DTD's in core so new
users will not be tempted to use deprecated ones.
However, it is not as simple as it may sound. For example, document1.3
extends document 1.2 which extends document 1.1, therefore for document
1.3 we need all earlier versions. It would therefore seem that the first
step would be to do as you propose, move the earlier DTD's into a
deprecated folder and think about the next step later.
Ross
Retirement of docs (Re: New documentation structure, next steps)
Posted by Ferdinand Soethe <sa...@soethe.net>.
> = 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.
Re: Documenting on documentation (Re: New documentation structure, next steps)
Posted by Ferdinand Soethe <sa...@soethe.net>.
Thorsten Scherler wrote:
> Nice work, David and Ferdinand.
Thanks for saying that. I was still kind of expecting somebody to come
forward and call for my head for this overnight coup de docs ...
> Thanks for doing this. :)
Welcome. I just couldn't resist. I guess you know that from views :-)
> I have spotted the rebirth of the Multipage HowTo example. I think I
> have a usecase (views). I can restructure the 3 single tutorials in one
> multipage how-to. Then we do not need this example anymore.
Haven't had time to actually read this. Don't bother, just add new ones. Will cull
the old stuff when there is time to actually understand what I'm
throwing out.
--
Ferdinand Soethe
Re: Documenting on documentation (Re: New documentation structure,
next steps)
Posted by Thorsten Scherler <th...@apache.org>.
On Tue, 2005-06-14 at 10:53 +0200, Ferdinand Soethe wrote:
>
>
>
> > - 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.
>
Nice work, David and Ferdinand.
Thanks for doing this. :)
I have spotted the rebirth of the Multipage HowTo example. I think I
have a usecase (views). I can restructure the 3 single tutorials in one
multipage how-to. Then we do not need this example anymore.
WDYT?
--
thorsten
"Together we stand, divided we fall!"
Hey you (Pink Floyd)
Documenting on documentation (Re: New documentation structure, next steps)
Posted by Ferdinand Soethe <sa...@soethe.net>.
> - 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.
Re: Prioriry Item: Fixing the list of changes (Re: New documentation structure, next steps)
Posted by Ferdinand Soethe <sa...@soethe.net>.
Ferdinand Soethe wrote:
> We could put 'Changes' back to the new 'docs' directory (still to
> be re-created) and it would work just fine. I'd be happy with that so
> why put more work into it. Unless sbdy else wants version specific
> changes.
Sorry, I just looked it up again and have to correct myself.
' put 'Changes' back to the 'xdocs' directory and it would work just
fine.'
--
Ferdinand Soethe
Re: Prioriry Item: Fixing the list of changes (Re: New documentation structure, next steps)
Posted by Ferdinand Soethe <sa...@soethe.net>.
Ross Gardler wrote:
> Like I've said before, tell me what projectInfo plugin does not do that
> you need and I will make it do it.
Thanks. I was hoping you'd offer :-)
But let people decide if we really need that.
We could put 'Changes' back to the new 'docs' directory (still to
be re-created) and it would work just fine. I'd be happy with that so
why put more work into it. Unless sbdy else wants version specific
changes.
--
Ferdinand Soethe
Re: Prioriry Item: Fixing the list of changes (Re: New documentation
structure, next steps)
Posted by Ross Gardler <rg...@apache.org>.
Ferdinand Soethe wrote:
>>= 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.
Like I've said before, tell me what projectInfo plugin does not do that
you need and I will make it do it.
Ross
Prioriry Item: Fixing the list of changes (Re: New documentation structure, next steps)
Posted by Ferdinand Soethe <sa...@soethe.net>.
> = 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.
Re: Treatment of non-versioned docs (Re: New documentation structure,
next steps)
Posted by Ross Gardler <rg...@apache.org>.
Ferdinand Soethe wrote:
>>- 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.
I'd say put a temporary hold on that, read on...
>>= 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.
The Locationmap is what you need for managing these docs. Wait until you
have the time to understand the locationmap and do it that way. I think
we will be able to design a great solution.
We can discuss after the locationmap branch is merged with trunk. (this
does not affect the MOTD idea, which I like)
Ross
Treatment of non-versioned docs (Re: New documentation structure, next steps)
Posted by Ferdinand Soethe <sa...@soethe.net>.
> - 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.
and this should also be part of this thread
> = 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.
Re: New documentation structure, next steps
Posted by David Crossley <cr...@apache.org>.
Ferdinand Soethe wrote:
>
> 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.
There was mutual mopping up.
Of course thanks to you too. We had a big job in front of us to
prepare the release candidate and to restructure the docs at the
same time. Ferdinand was just as tireless, we both watched the
sun rise from different parts of the world.
> 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.
Yes, it is a good base.
--David