You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by Jeff Turner <je...@apache.org> on 2002/11/12 15:58:29 UTC
Forrest is overdocumented
I never thought I'd say it of an Apache project, but there you go.. :)
Users are practically swimming in documentation, unfortunately mostly
slightly out of date. I foolishly tried to update the Forrest Primer,
and found that outdated xml.apache.org-centricity is absolutely
everywhere. Rewriting an existing doc is actually more effort than
writing one from scratch, because added content has to 'fit', not
duplicating anything. The change 'infects' the doc around it, requiring
a cascade of updates. primer.xml is a nightmare because it touches
everything.
IMO the site needs a ground-up rewrite, containing the absolute minimum
of content. We could have a separate tab, 'legacy', containing the
current site.
</rant>
:)
Though I must say, the quality of Forrest's docs (before the code changed
under it) says a lot about the dedication of Forrest's committers. The
site authors all deserve some serious toothbrush awards.
--Jeff
Re: Forrest is overdocumented
Posted by Steven Noels <st...@outerthought.org>.
Jeff Turner wrote:
> Users are practically swimming in documentation, unfortunately mostly
> slightly out of date. I foolishly tried to update the Forrest Primer,
> and found that outdated xml.apache.org-centricity is absolutely
> everywhere. Rewriting an existing doc is actually more effort than
> writing one from scratch, because added content has to 'fit', not
> duplicating anything. The change 'infects' the doc around it, requiring
> a cascade of updates. primer.xml is a nightmare because it touches
> everything.
Yeah. That was the idea, basically, since there was no real
documentation at that time. The same will hold true for your-project.xml
in a month or two, too. We need to componentize our documentation in a
set of interrelated, but independently managed snippets, that have the
same level of updateability as status.xml.
> IMO the site needs a ground-up rewrite, containing the absolute minimum
> of content. We could have a separate tab, 'legacy', containing the
> current site.
>
> </rant>
No, <truth/>
Now, let's fill this empty element :-D
> :)
>
> Though I must say, the quality of Forrest's docs (before the code changed
> under it) says a lot about the dedication of Forrest's committers. The
> site authors all deserve some serious toothbrush awards.
Since we all claim to be docowizards, let's try to achieve the same
level of granularity the httpd docs have
(http://httpd.apache.org/docs-2.0/).
So what are the main components of Forrest?
* featurewise / use-case driven
- installation & configuration
- seeding & first steps
- dtd user documentation
- 'cron'-ing forrest
- ...
* technically
- grammars & CAP
- uri namespace
- pipelines
- skins
- forrestbot
- ...
Later on, we can add 'trails' that lead people to the correct info.
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
Read my weblog at http://radio.weblogs.com/0103539/
stevenn at outerthought.org stevenn at apache.org
Re: Forrest is overdocumented
Posted by "Andrew C. Oliver" <ac...@apache.org>.
I was thinking more on the order of the html documentation being
generated from these blocks...
Jeff Turner wrote:
>On Tue, Nov 12, 2002 at 10:25:12AM -0500, Andrew C. Oliver wrote:
>
>Mm.. expiry dates, doc-to-content links.. interesting.
>
>
>
>>Secondly. Move the documentation as close to the code as possible while
>>making the conceptual documentation depend on it!
>>
>>
>
>Currently, build.xml and forrest.build.xml have lots of <echo> blocks
>describing what to do next. Eg, at the end of 'forrest webapp':
>
>---------------------------------
>Webapp generated in /tmp/mysite/build/webapp
>
>To run in Tomcat, add this to the config file (usu. server.xml):
>
><Context path='/MyProject'
> docBase='/tmp/mysite/build/webapp'
> reloadable='true'/>
>
>If using JDK 1.4 or above, make sure to set the Java environment variable
>-Djava.endorsed.dirs=/home/jeff/apache/xml/xml-forrest/build/dist/shbat/bin/../lib/endorsed
>Eg, in the TOMCAT_OPTS (3.3.x) or CATALINA_OPTS (4.x) env variable.
>---------------------------------
>
>Perhaps we should keep these snippets in XML entity files which we &import;
>into the build scripts and documentation.
>
>--Jeff
>
>
>
Re: Forrest is overdocumented
Posted by Jeff Turner <je...@apache.org>.
On Tue, Nov 12, 2002 at 10:25:12AM -0500, Andrew C. Oliver wrote:
Mm.. expiry dates, doc-to-content links.. interesting.
> Secondly. Move the documentation as close to the code as possible while
> making the conceptual documentation depend on it!
Currently, build.xml and forrest.build.xml have lots of <echo> blocks
describing what to do next. Eg, at the end of 'forrest webapp':
---------------------------------
Webapp generated in /tmp/mysite/build/webapp
To run in Tomcat, add this to the config file (usu. server.xml):
<Context path='/MyProject'
docBase='/tmp/mysite/build/webapp'
reloadable='true'/>
If using JDK 1.4 or above, make sure to set the Java environment variable
-Djava.endorsed.dirs=/home/jeff/apache/xml/xml-forrest/build/dist/shbat/bin/../lib/endorsed
Eg, in the TOMCAT_OPTS (3.3.x) or CATALINA_OPTS (4.x) env variable.
---------------------------------
Perhaps we should keep these snippets in XML entity files which we &import;
into the build scripts and documentation.
--Jeff
Re: Forrest is overdocumented
Posted by "Andrew C. Oliver" <ac...@apache.org>.
> Nice.
>
>> Secondly. Move the documentation as close to the code as possible while
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
>> making the conceptual documentation depend on it!
>
>
> User request number 1.
> Keep tracking guys ;-)
>
But please read again DO NOT ELIMNATE CONCEPTUAL DOCUMENTATION! Just
enhance "compile-time-checking" ;-)
>
>>
>>
>> Nicola Ken Barozzi wrote:
>>
>>>
>>> Jeff Turner wrote:
>>>
>>>> I never thought I'd say it of an Apache project, but there you go.. :)
>>>
>>>
>>>
>>>
>>> Keep this mail as a reference for future discussions on the "Avalon
>>> Documentation Team" ;-)
>>>
>>>> Users are practically swimming in documentation, unfortunately mostly
>>>> slightly out of date. I foolishly tried to update the Forrest Primer,
>>>> and found that outdated xml.apache.org-centricity is absolutely
>>>> everywhere. Rewriting an existing doc is actually more effort than
>>>> writing one from scratch, because added content has to 'fit', not
>>>> duplicating anything. The change 'infects' the doc around it,
>>>> requiring
>>>> a cascade of updates. primer.xml is a nightmare because it touches
>>>> everything.
>>>
>>>
>>>
>>>
>>> Since I seem to be the "let's make a tool to solve the problem"-man,
>>> here goes the tool ;-P
>>>
>>> I had presented this before, and now is the case it could have
>>> helped (maybe?).
>>> That is keep in the document the "expiry date" of the document
>>> itself, and eventually its binding with other document update dates.
>>>
>>> For example, we could say that if build.xml has changes for a week,
>>> the primer document may be stale...
>>>
>>> Just a RT in the midst of Jeff's rantings...
>>>
>>>> IMO the site needs a ground-up rewrite, containing the absolute
>>>> minimum
>>>> of content. We could have a separate tab, 'legacy', containing the
>>>> current site.
>>>>
>>>> </rant>
>>>>
>>>> :)
>>>>
>>>> Though I must say, the quality of Forrest's docs (before the code
>>>> changed
>>>> under it) says a lot about the dedication of Forrest's committers.
>>>> The
>>>> site authors all deserve some serious toothbrush awards.
>>>
>>>
>>>
>>>
>>> +1
>>>
>>
>>
>>
>>
>
Re: Forrest is overdocumented
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Andrew C. Oliver wrote:
> I'm verklempt.... I need a moment....talk amongst yourselves....here
> I'll give you a topic
> "
> Compilable dependency resolution. I'll leave the XML->XML version of
> this to the geniuses but for the java version any contract mentioned in
> the documentation should have an <element-dependancy
> classname="org.apache.poi.hssf.usermodel.HSSFCell"
> method="getFormat(int)"/> and if ever the getFormat(int) method goes
> away or something the compilation of the XML will fail and I'll be
> forced to update it.
Nice.
> Secondly. Move the documentation as close to the code as possible while
^^^^^^^^^^^^^^^^^^^^^^^^^^^
> making the conceptual documentation depend on it!
User request number 1.
Keep tracking guys ;-)
>
>
> Nicola Ken Barozzi wrote:
>
>>
>> Jeff Turner wrote:
>>
>>> I never thought I'd say it of an Apache project, but there you go.. :)
>>
>>
>>
>> Keep this mail as a reference for future discussions on the "Avalon
>> Documentation Team" ;-)
>>
>>> Users are practically swimming in documentation, unfortunately mostly
>>> slightly out of date. I foolishly tried to update the Forrest Primer,
>>> and found that outdated xml.apache.org-centricity is absolutely
>>> everywhere. Rewriting an existing doc is actually more effort than
>>> writing one from scratch, because added content has to 'fit', not
>>> duplicating anything. The change 'infects' the doc around it, requiring
>>> a cascade of updates. primer.xml is a nightmare because it touches
>>> everything.
>>
>>
>>
>> Since I seem to be the "let's make a tool to solve the problem"-man,
>> here goes the tool ;-P
>>
>> I had presented this before, and now is the case it could have helped
>> (maybe?).
>> That is keep in the document the "expiry date" of the document itself,
>> and eventually its binding with other document update dates.
>>
>> For example, we could say that if build.xml has changes for a week,
>> the primer document may be stale...
>>
>> Just a RT in the midst of Jeff's rantings...
>>
>>> IMO the site needs a ground-up rewrite, containing the absolute minimum
>>> of content. We could have a separate tab, 'legacy', containing the
>>> current site.
>>>
>>> </rant>
>>>
>>> :)
>>>
>>> Though I must say, the quality of Forrest's docs (before the code
>>> changed
>>> under it) says a lot about the dedication of Forrest's committers. The
>>> site authors all deserve some serious toothbrush awards.
>>
>>
>>
>> +1
>>
>
>
>
>
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: Forrest is overdocumented
Posted by "Andrew C. Oliver" <ac...@apache.org>.
>
>
>>
>>
>> You're wrong.
>
>
> Please, let's not polarize what might be a very interesting thread.
My sincere appologies, I'm conducting an experiment in sleep deprevation
and high levels of stress and what effect they have on my already
tactless personality with deficient e-mail tact skills. what I meant
to say "I disagree with that viewpoint...have you considered..."
>
>> This is like saying "import statements" should just be guessed at
>> because worrying about what dependencies the code has will overwhelm
>> the developers/users...
>
>
> I don't think that's a fair analogy. Your example referred to methods,
> not classes... And by overwhelming, I'm not talking about "worrying"
> users or committers, but about how such potentially voluminous
> feedback (during a build) will be processed (e.g. not ignored).
No...thats still fair. The compiler does this for code.. So I'm just
saying...Extend it...Do it for docs. We're kinda sorta seeing the
opposite effect...extending the documentation to control the code
(xdoclet)....flip it over. If the documentation depends on the
code..check for it. If you're getting volumnous feedback, you have
volumes of doc work to do.
>
>> (I'm not sure what hte user has to do with the doc part either...the
>> tool is supposed to resolve it)
>
>
> By user I meant users who contribute/patch docs. There is a growing
> number of these kind of users, at least on Cocoon.
And presumably they learned this information from somewhere right? Was
it a config file? Well presumably a developer write some documentation
in the config file... If he documents that documentation's dependency,
the documentation developer whom is also a user can site that
documetnation and the dependency tree is maintained.
>>
>> Well presumably your documenting lower level concepts at a higher
>> level. Presumably the higher level documentation should DEPEND upon
>> the lower level docuemntation, include portions where possible, and
>> specify dependencies upon it.
>> <doc-depend class="org.apache.bla" method="doda(int)"/> in the low
>> level docs...
>
>
> Problem is, there's isn't always a clean 1-to-1 mapping, especially
> when dealing with layers of the architectural and user models. Can you
> think of a way we could deal with a subset of code/components when
> documenting such dependencies? Think about a document about the
> sitemap for Cocoon. Imagine how many dependencies it would have if you
> included all associated methods.
So you're saying this won't work ALL of the time. Agreed. My response
(and I mean this in the most tactful way) is "so what?" What
percentage improvement makes this worthwhile?
>
> Yes, but having it similar to javadocs sounds redundant.
Okay....so maybe its not a good idea... I dunno. I don't presently
have time to POC it out so I just thought I'd throw it out there. Maybe
I'm wrong...that happens.
What I am positive I'm right on is the title of this thread. That is
complete (and excuse how harsh this is) bunk. You cannot overdocument.
But you say you can have reams and reams of documentation that is
useless and (not to say we do just for the purpose of demonstrating this
point) not up to day. That is UNDER documentation. You've put
insufficient effort into organizing it, editing it and updating it. So
its still UNDER-documetnation. you can NEVER over document until your
user has a complete intuitive understanding and you're telling him how
to brush his teeth before he uses the software... (silly, but I mean it)...
So effort needs to be put into EFFECTIVELY documenting it, not volume.
For isntance, I send about 200x as many emails as Stefano. But it
takes me that many to get my point accross because I'm not that good at
email communication (sucks to be me). I also don't often put enough
time and consideration into the effort, where stefano does. This isn't
to say I'm over-emailing, I'm still under emailing. One Stefano email
gets the point accross much better because he puts way more thought and
effort into it. Same thing with doco... (Only thats one thing I'm
better at then most... ;-) )...
-Andy
>
> Diana
>
>
Re: Forrest is overdocumented
Posted by Diana Shannon <sh...@apache.org>.
On Wednesday, November 13, 2002, at 09:13 AM, Andrew C. Oliver wrote:
>> I fear this approach is a bit oversimplistic, paticularly for projects
>> with large amounts of code. Some docs would have dependencies on
>> *many* classes. Potential contract violations (revealed during the
>> build process??) would overwhelm committers/users.
>
>
> You're wrong.
Please, let's not polarize what might be a very interesting thread.
> This is like saying "import statements" should just be guessed at
> because worrying about what dependencies the code has will overwhelm
> the developers/users...
I don't think that's a fair analogy. Your example referred to methods,
not classes... And by overwhelming, I'm not talking about "worrying"
users or committers, but about how such potentially voluminous feedback
(during a build) will be processed (e.g. not ignored).
> (I'm not sure what hte user has to do with the doc part either...the
> tool is supposed to resolve it)
By user I meant users who contribute/patch docs. There is a growing
number of these kind of users, at least on Cocoon.
>
>>
>>> Secondly. Move the documentation as close to the code as possible
>>> while making the conceptual documentation depend on it!
>>
>>
>> Can you elaborate?
>
> Well presumably your documenting lower level concepts at a higher
> level. Presumably the higher level documentation should DEPEND upon the
> lower level docuemntation, include portions where possible, and specify
> dependencies upon it.
> <doc-depend class="org.apache.bla" method="doda(int)"/> in the low
> level docs...
Problem is, there's isn't always a clean 1-to-1 mapping, especially when
dealing with layers of the architectural and user models. Can you think
of a way we could deal with a subset of code/components when documenting
such dependencies? Think about a document about the sitemap for Cocoon.
Imagine how many dependencies it would have if you included all
associated methods.
> At the high level you should be including sections of the low level
> docs (DONT REPEAT YOURSELF) and then <doc-depend doc="blabla.xml"
> section="bla"/> -- Then if the low level doc is broken, the high level
> doc is marked broken as well. Or if the low level doc deletes that
> section...the high level doc is broken as well. Furthermore high level
> docs might depend upon code structures as well. For instance, in the
> case of ANT if I'm describing how to use the JUNIT task and I'm
> describing the printsummary attribute, I can obviously refer to that
> attribute in the low level implementation of the Junit taks (which I
> think is
> org.apache.ant.somethingsomething.tasks.JUnitTask.setPrintSummary
> (bla) ) --
> This will catch things like changes in how configuration files work,
> directory structure, etc. It won't catch functionality changes. If
> I'm describing how printsummary works and now suddenly it does
> something different but has the same attributes/etc... This won't catch
> that. But thats crappy programming probably anyhow.
>
> I think this will help reduce the weight of maintaining documentation
> on developers and its invisible to users anyhow. Its drawback is that
> it may not always be natural to create a heirarchial structure that
> this seems to dictate, but I think its clean...
>
> The rest of the time the documentation should be as close to the code
> as possible...I'm not sure how much more I can elaborate on that....
> Like Javadoc kinda sorta...
Yes, but having it similar to javadocs sounds redundant.
Diana
Re: Forrest is overdocumented
Posted by "Andrew C. Oliver" <ac...@apache.org>.
> I fear this approach is a bit oversimplistic, paticularly for projects
> with large amounts of code. Some docs would have dependencies on
> *many* classes. Potential contract violations (revealed during the
> build process??) would overwhelm committers/users.
You're wrong. This is like saying "import statements" should just be
guessed at because worrying about what dependencies the code has will
overwhelm the developers/users... (I'm not sure what hte user has to do
with the doc part either...the tool is supposed to resolve it)
>
>> Secondly. Move the documentation as close to the code as possible
>> while making the conceptual documentation depend on it!
>
>
> Can you elaborate?
Well presumably your documenting lower level concepts at a higher level.
Presumably the higher level documentation should DEPEND upon the lower
level docuemntation, include portions where possible, and specify
dependencies upon it.
<doc-depend class="org.apache.bla" method="doda(int)"/> in the low level
docs...
At the high level you should be including sections of the low level docs
(DONT REPEAT YOURSELF) and then <doc-depend doc="blabla.xml"
section="bla"/> -- Then if the low level doc is broken, the high level
doc is marked broken as well. Or if the low level doc deletes that
section...the high level doc is broken as well. Furthermore high level
docs might depend upon code structures as well. For instance, in the
case of ANT if I'm describing how to use the JUNIT task and I'm
describing the printsummary attribute, I can obviously refer to that
attribute in the low level implementation of the Junit taks (which I
think is
org.apache.ant.somethingsomething.tasks.JUnitTask.setPrintSummary(bla) )
--
This will catch things like changes in how configuration files work,
directory structure, etc. It won't catch functionality changes. If I'm
describing how printsummary works and now suddenly it does something
different but has the same attributes/etc... This won't catch that. But
thats crappy programming probably anyhow.
I think this will help reduce the weight of maintaining documentation on
developers and its invisible to users anyhow. Its drawback is that it
may not always be natural to create a heirarchial structure that this
seems to dictate, but I think its clean...
The rest of the time the documentation should be as close to the code as
possible...I'm not sure how much more I can elaborate on that.... Like
Javadoc kinda sorta...
-Andy
>
> Diana
>
>
Re: Forrest is overdocumented
Posted by Diana Shannon <sh...@apache.org>.
On Tuesday, November 12, 2002, at 10:25 AM, Andrew C. Oliver wrote:
> Compilable dependency resolution. I'll leave the XML->XML version of
> this to the geniuses but for the java version any contract mentioned in
> the documentation should have an <element-dependancy
> classname="org.apache.poi.hssf.usermodel.HSSFCell"
> method="getFormat(int)"/> and if ever the getFormat(int) method goes
> away or something the compilation of the XML will fail and I'll be
> forced to update it.
I fear this approach is a bit oversimplistic, paticularly for projects
with large amounts of code. Some docs would have dependencies on *many*
classes. Potential contract violations (revealed during the build
process??) would overwhelm committers/users.
> Secondly. Move the documentation as close to the code as possible
> while making the conceptual documentation depend on it!
Can you elaborate?
Diana
Re: Forrest is overdocumented
Posted by "Andrew C. Oliver" <ac...@apache.org>.
I'm verklempt.... I need a moment....talk amongst yourselves....here
I'll give you a topic
"
Compilable dependency resolution. I'll leave the XML->XML version of
this to the geniuses but for the java version any contract mentioned in
the documentation should have an <element-dependancy
classname="org.apache.poi.hssf.usermodel.HSSFCell"
method="getFormat(int)"/> and if ever the getFormat(int) method goes
away or something the compilation of the XML will fail and I'll be
forced to update it.
Secondly. Move the documentation as close to the code as possible while
making the conceptual documentation depend on it!
"
Nicola Ken Barozzi wrote:
>
> Jeff Turner wrote:
>
>> I never thought I'd say it of an Apache project, but there you go.. :)
>
>
> Keep this mail as a reference for future discussions on the "Avalon
> Documentation Team" ;-)
>
>> Users are practically swimming in documentation, unfortunately mostly
>> slightly out of date. I foolishly tried to update the Forrest Primer,
>> and found that outdated xml.apache.org-centricity is absolutely
>> everywhere. Rewriting an existing doc is actually more effort than
>> writing one from scratch, because added content has to 'fit', not
>> duplicating anything. The change 'infects' the doc around it, requiring
>> a cascade of updates. primer.xml is a nightmare because it touches
>> everything.
>
>
> Since I seem to be the "let's make a tool to solve the problem"-man,
> here goes the tool ;-P
>
> I had presented this before, and now is the case it could have helped
> (maybe?).
> That is keep in the document the "expiry date" of the document itself,
> and eventually its binding with other document update dates.
>
> For example, we could say that if build.xml has changes for a week,
> the primer document may be stale...
>
> Just a RT in the midst of Jeff's rantings...
>
>> IMO the site needs a ground-up rewrite, containing the absolute minimum
>> of content. We could have a separate tab, 'legacy', containing the
>> current site.
>>
>> </rant>
>>
>> :)
>>
>> Though I must say, the quality of Forrest's docs (before the code
>> changed
>> under it) says a lot about the dedication of Forrest's committers. The
>> site authors all deserve some serious toothbrush awards.
>
>
> +1
>
Re: Forrest is overdocumented
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Jeff Turner wrote:
> I never thought I'd say it of an Apache project, but there you go.. :)
Keep this mail as a reference for future discussions on the "Avalon
Documentation Team" ;-)
> Users are practically swimming in documentation, unfortunately mostly
> slightly out of date. I foolishly tried to update the Forrest Primer,
> and found that outdated xml.apache.org-centricity is absolutely
> everywhere. Rewriting an existing doc is actually more effort than
> writing one from scratch, because added content has to 'fit', not
> duplicating anything. The change 'infects' the doc around it, requiring
> a cascade of updates. primer.xml is a nightmare because it touches
> everything.
Since I seem to be the "let's make a tool to solve the problem"-man,
here goes the tool ;-P
I had presented this before, and now is the case it could have helped
(maybe?).
That is keep in the document the "expiry date" of the document itself,
and eventually its binding with other document update dates.
For example, we could say that if build.xml has changes for a week, the
primer document may be stale...
Just a RT in the midst of Jeff's rantings...
> IMO the site needs a ground-up rewrite, containing the absolute minimum
> of content. We could have a separate tab, 'legacy', containing the
> current site.
>
> </rant>
>
> :)
>
> Though I must say, the quality of Forrest's docs (before the code changed
> under it) says a lot about the dedication of Forrest's committers. The
> site authors all deserve some serious toothbrush awards.
+1
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------