You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@velocity.apache.org by Nathan Bubna <na...@esha.com> on 2003/11/05 18:42:56 UTC
[veltools] Tool documentation
hey folks,
i'm looking for people's opinions about the way we document tools. Back in
the early days, Gabe developed a dvsl format for providing user-friendly,
comprehensive tool documentation. (see
http://jakarta.apache.org/velocity/tools/generic/index.html for some
explanation or
http://jakarta.apache.org/velocity/tools/struts/MessageTool.html for a good
example)
As we move closer to a 1.1 release, updating and filling out documentation is
becoming very important. I'd like to know if people still see this dvsl
documentation of tools as really useful and worth the significant effort it
takes to create it and then keep it in sync with the actual code.
Nathan Bubna
nathan@esha.com
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: [veltools] Tool documentation
Posted by Dave Newton <da...@solaraccess.com>.
On Wed, 2003-11-05 at 14:11, Nathan Bubna wrote:
> it's not so much the dvsl-ness of it that i was asking about. it's the
> end-format and the effort.
Oh. Sorry.
> basically, i'm asking if the gains in information and readability (as opposed
> to javadoc) of providing tool documentation in that format is worth the extra
> effort. and it is a fair bit of extra effort! with javadoc, it is relatively
> easy to keep the documentation in sync with the actual code, you just document
> the class and methods right in the code as you go.
In that case I'd probably say no, it's not worth it, and could/will lead
to bit-rot in the docs.
Of course, I haven't had a chance to do essentially _anything_ since I
wanted to start working with Velocity, so I should keep my mouth shut
anyway :/
Dave
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: [veltools] Tool documentation
Posted by Nathan Bubna <na...@esha.com>.
Dave Newton said:
> On Wed, 2003-11-05 at 13:26, Mike Kienenberger wrote:
> > I think you're asking on the wrong mailing list. This is more of a user
> > question than a dev question.
>
> Except the developers write the documentation. (Everything works in
> theory, right? ;)
>
> I'm all for great documentation. I don't know that I care about the
> dvsl-ness of it.
it's not so much the dvsl-ness of it that i was asking about. it's the
end-format and the effort.
basically, i'm asking if the gains in information and readability (as opposed
to javadoc) of providing tool documentation in that format is worth the extra
effort. and it is a fair bit of extra effort! with javadoc, it is relatively
easy to keep the documentation in sync with the actual code, you just document
the class and methods right in the code as you go. while i agree that Gabe's
format is more readable, it needn't necessarily be more informative than
javadoc is, and it requires creating and maintaining a separate xml file for
each tool. i want to know if you guys think it's worth it or if we should
just focus on improving the javadocs.
of course, this only applies to documenting individual tools themselves. i
definitely don't think javadoc is sufficient for documenting the project as a
whole.
Nathan Bubna
nathan@esha.com
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: [veltools] Tool documentation
Posted by Dave Newton <da...@solaraccess.com>.
On Wed, 2003-11-05 at 13:26, Mike Kienenberger wrote:
> I think you're asking on the wrong mailing list. This is more of a user
> question than a dev question.
Except the developers write the documentation. (Everything works in
theory, right? ;)
I'm all for great documentation. I don't know that I care about the
dvsl-ness of it.
Dave
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: [veltools] Tool documentation
Posted by Nathan Bubna <na...@esha.com>.
Mike Kienenberger said:
> Nathan Bubna <na...@esha.com> wrote:
> > i'm looking for people's opinions about the way we document tools. Back
> in
> > the early days, Gabe developed a dvsl format for providing user-friendly,
> > comprehensive tool documentation.
> >
> > As we move closer to a 1.1 release, updating and filling out documentation
> is
> > becoming very important. I'd like to know if people still see this dvsl
> > documentation of tools as really useful and worth the significant effort
> it
> > takes to create it and then keep it in sync with the actual code.
>
> I think you're asking on the wrong mailing list. This is more of a user
> question than a dev question.
i think it's a very valid question here. presumably people on the dev list
are those who would be creating and/or contributing to the project
documentation. as such, i think their opinions on the matter are very
pertinent. :)
> That said, back when I was learning velocity tools, I made extensive use of
> that documentation.
> Now that I've "learned" it, I only occasionally use it for reference.
i suppose i should take that as a "yes" from you? :)
Nathan Bubna
nathan@esha.com
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: [veltools] Tool documentation
Posted by Mike Kienenberger <mk...@alaska.net>.
Nathan Bubna <na...@esha.com> wrote:
> i'm looking for people's opinions about the way we document tools. Back
in
> the early days, Gabe developed a dvsl format for providing user-friendly,
> comprehensive tool documentation.
>
> As we move closer to a 1.1 release, updating and filling out documentation
is
> becoming very important. I'd like to know if people still see this dvsl
> documentation of tools as really useful and worth the significant effort
it
> takes to create it and then keep it in sync with the actual code.
I think you're asking on the wrong mailing list. This is more of a user
question than a dev question.
That said, back when I was learning velocity tools, I made extensive use of
that documentation.
Now that I've "learned" it, I only occasionally use it for reference.
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
RE: [veltools] Tool documentation
Posted by Tim Colson <tc...@cisco.com>.
> IME, good package.html's work fine.
> The typical approach that seemed to
> work was to start each package.html with a list of the "key" classes
> from that package, and a brief explanation of each, followed by the
> overview of the package, and then separate headings covering usage,
> advice, examples, etc.
Sounds great! Although I still think I would prefer a User Guide so
users would not have to hunt through a bunch of package definitions (ex.
tools has 8, Velocity core 30).
I get frustrated digging into an API javadoc with 1000+
classes/interfaces, and prefer a userguide "How to get started" section.
:-)
> I would *never* complain about jdoc bloat
Hah. I'm picky and impatient. <grin>
I like a guide with "essentials" - and then Javadoc as a complete
reference for when I know I need to dig deeper into the guts of a
particular class.
Say - that shows a distinction I keep subconsciously making...
In my opinion: Developers need to know about tool "classes".
but: Designers want to how to use the "tool" in the Template.
This is another reason I don't like the Javadoc format - they are geared
toward us Developer types. For the TOOLS, I expect my Designer friends
to be the primary users - and I know from experience they just want to
be shown how to use the tool, and generally do not understand nor care
to learn that "javax.servlet.http.Cookie[]" means they can use
woogie.getAll() in a #foreach statement.
Cheers,
Timo
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: [veltools] Tool documentation
Posted by specialist33 <sp...@grexengine.com>.
Tim Colson wrote:
>>javadoc is HTML :)
>
> :-P
> Okay, let me rephrase: I think I can write HTML pages that are easier to
> understand and navigate than most javadocs.
>
>
>>i really don't have any problem with javadoc format.
>
> I've never been a big fan. The format adds bloat (ex. Methods inherited
> from java.lang.Object are wait, wait, wait). Navigation by package does
> not highlight what is important in the big bag of classes. Heirarchies
> usually make sense AFTER you know where things fit in them. So for
> newbies, they do not know what they need to know, nor where to go
> looking for details.
>
>
>>we just need to be sure
>>we have docs somewhere that give an overview. these could be the
>>package.html, but i don't generally feel those are sufficient
>>or noticeable enough.
>>i'd rather keep overview type stuff to the dvsl docs.
>
> Agreed.
>
IME, good package.html's work fine. I have been unfortunate enough to
work on half a dozen projects where we were licensing 3rd party software
whose entire documentation was jdoc. None of the User Guide, Admin
Guide, Manual, Programmers Reference etc that I'm used to :(.
However, in all but one case the package.html's were so good that there
was no problem for us as developers. The typical approach that seemed to
work was to start each package.html with a list of the "key" classes
from that package, and a brief explanation of each, followed by the
overview of the package, and then separate headings covering usage,
advice, examples, etc.
Some people preferred having it all in one browseable doc collection;
I'm still sitting on the fence, but I can see that jdoc is pretty good
if you use it intelligently.
FWIW, I've so many times had to use API documentation that ommitted
things the author thought were irrelevant, but which it was helpful to
know were there, that I would *never* complain about jdoc bloat
(although I appreciate your point - I would really like it if the jdocs
worked like a folding text editor when looking at long classes, but
sadly HTML doesn't do this easily. Perhaps a fourth nav-frame for
navigating the methods and fields of the currently-viewed class?)
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
RE: [veltools] Tool documentation
Posted by Tim Colson <tc...@cisco.com>.
> javadoc is HTML :)
:-P
Okay, let me rephrase: I think I can write HTML pages that are easier to
understand and navigate than most javadocs.
> i really don't have any problem with javadoc format.
I've never been a big fan. The format adds bloat (ex. Methods inherited
from java.lang.Object are wait, wait, wait). Navigation by package does
not highlight what is important in the big bag of classes. Heirarchies
usually make sense AFTER you know where things fit in them. So for
newbies, they do not know what they need to know, nor where to go
looking for details.
> we just need to be sure
> we have docs somewhere that give an overview. these could be the
> package.html, but i don't generally feel those are sufficient
> or noticeable enough.
> i'd rather keep overview type stuff to the dvsl docs.
Agreed.
Still wondering if we could somehow just create a special section in the
javadoc comments that could be pulled 'up' into the DVSL docs
automagically. Keep maintenance simple, and overview presentation a bit
easier to read.
Tim
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: [veltools] Tool documentation
Posted by Nathan Bubna <na...@esha.com>.
Tim Colson said:
...
> > thus, i don't feel the additional dvsl docs for *each
> > individual view tool*
> > are worth the extra effort to maintain and develop.
> +1 (I think I agreed before with this, didn't I? <grin>)
i thought so. just wasn't sure. :)
...
> > a single page doc for all tools? or a single page for each
> > tools.
> A single page that lists all tools. Just the relevant bits that are
> required for Developers to know. Which is mostly just the toolbox xml, I
> think?
sounds like a decent idea. something to bridge the three subprojects. a good
start to a dev-guide at least. we could go on from there to designing your
own view tools and other config/design issues.
> > i'd suggest looking at my recent documentation changes online
> > for examples of this.
> Help me out with a link/filename to look at, please.
-go to http://jakarta.apache.org/velocity/tools/index.html
-select a subproject on the bottom left.
-then you'll see a list of tools center-left.
-click on a tool name. (note: some older tool links still point to old
format)
-observe.
some of the more substantial tool docs are the DateTool and the
AbstractSearchTool.
> > > Designers, something more tangible like the User-Guide doc.
> > yes, but this issue is tangental to what i was talking about.
> Ok...I'm [still] not seeing it as being far off the topic.
agreed. it's not far. in fact, it's even touching the topic, but it takes it
in a different direction than i was going. thus "tangental." :)
> > can you explain better what you have in mind instead?
> Ha... I tried to do that in the "Designer needs to know" bit... I
> basically added a little bit of 'narrative' telling folks why the tool
> is useful and then copied Gabes quick example of how to use it.
>
> I'm thinking that all of these "what Designers really need to know"
> could be thrown into a single page in a Tools User Guide.
could be a good start to a user-guide.
> Again - I do like what Gabe started, HTML is far more accessible to a
> Designer than Javadoc... but I doubt a designer would grok:
javadoc is HTML :)
> ---------------
> ArrayList get(String property)
> - returns A java.util.ArrayList of java.lang.String
> ---------------
yeah, that's pretty weak. but that's by no means all that javadoc can do. i
see javadoc as a format-provider not a content-provider. the
developers/contributers still need to put useful information in the javadocs.
not many do, but i always make an effort to do so because i find the javadoc
format/organization convenient for developers to maintain and fairly
straightforward for users to traverse/read. but again, you get out what you
put in.
> I have two thoughts:
> 1) cut out and simplify the stuff Gabe created, combining into one doc
> with a Designer in mind. Place all Developer specific tool config into
> another doc.
sure. but of course, we need someone to actually do it. :)
> 2) Enhance the javadoc to include "Designer friendly" sections (as
> described in #1 and above)... and then somehow convert that javadoc into
> the HTML for the site.
i've been working on this as i work on the code. and again, javadoc already
gets automatically converted to HTML and has long been part of the site.
> First option would make things simple to understand for both audiences,
> but still involve some duplication and syncing of doc with code (no
> different from most docs). Second option would make maintenance easier,
> and still make it easier for Designers to figure out how to use these
> tools, but _might_ not be as easy to customize the end format.
i really don't have any problem with javadoc format. we just need to be sure
we have docs somewhere that give an overview. these could be the
package.html, but i don't generally feel those are sufficient or noticeable
enough. i'd rather keep overview type stuff to the dvsl docs.
> Isn't there some funky tool for creating a javadoclet thingy that might
> help with the auto-conversion?
i dunno.
Nathan Bubna
nathan@esha.com
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
RE: [veltools] Tool documentation
Posted by Tim Colson <tc...@cisco.com>.
> current documentation format doesn't offer much more than
> javadoc format does.
+1
> thus, i don't feel the additional dvsl docs for *each
> individual view tool*
> are worth the extra effort to maintain and develop.
+1 (I think I agreed before with this, didn't I? <grin>)
> i did not suggest we ONLY
> use javadoc. you read in too far.
Ok. It had sounded like the question was about yanking Gabe's stuff in
favor of just Javadoc.
> a single page doc for all tools? or a single page for each
> tools.
A single page that lists all tools. Just the relevant bits that are
required for Developers to know. Which is mostly just the toolbox xml, I
think?
> i'd suggest looking at my recent documentation changes online
> for examples of this.
Help me out with a link/filename to look at, please.
> > Designers, something more tangible like the User-Guide doc.
> yes, but this issue is tangental to what i was talking about.
Ok...I'm [still] not seeing it as being far off the topic.
> can you explain better what you have in mind instead?
Ha... I tried to do that in the "Designer needs to know" bit... I
basically added a little bit of 'narrative' telling folks why the tool
is useful and then copied Gabes quick example of how to use it.
I'm thinking that all of these "what Designers really need to know"
could be thrown into a single page in a Tools User Guide.
Again - I do like what Gabe started, HTML is far more accessible to a
Designer than Javadoc... but I doubt a designer would grok:
---------------
ArrayList get(String property)
- returns A java.util.ArrayList of java.lang.String
---------------
I have two thoughts:
1) cut out and simplify the stuff Gabe created, combining into one doc
with a Designer in mind. Place all Developer specific tool config into
another doc.
2) Enhance the javadoc to include "Designer friendly" sections (as
described in #1 and above)... and then somehow convert that javadoc into
the HTML for the site.
First option would make things simple to understand for both audiences,
but still involve some duplication and syncing of doc with code (no
different from most docs). Second option would make maintenance easier,
and still make it easier for Designers to figure out how to use these
tools, but _might_ not be as easy to customize the end format.
Isn't there some funky tool for creating a javadoclet thingy that might
help with the auto-conversion?
-Timo
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: [veltools] Tool documentation
Posted by Nathan Bubna <na...@esha.com>.
Tim Colson said:
> Nathan asked:
> > I'd like to know if people still see this dvsl
> > documentation of tools as really useful and
> > worth the significant effort it
>
> -1
> (I appreciate that Gabe created docs, but I think the content could be
> presented more plainly for users.)
>
> -1 on Nathan's suggestion to ONLY use Javadoc.
hmm. i'm not sure we're tracking here. my point was that i didn't feel the
current documentation format doesn't offer much more than javadoc format does.
thus, i don't feel the additional dvsl docs for *each individual view tool*
are worth the extra effort to maintain and develop. i did not suggest we ONLY
use javadoc. you read in too far.
> Why? I think we have two audiences (Developers & Designers) and believe
> each need different documentation. I think we could create for
> Developers a single-page doc on tools and configuration.
a single page doc for all tools? or a single page for each tools. the latter
is what Gabe's format provided, i believe javadoc can do the same with less
effort. i'd suggest looking at my recent documentation changes online for
examples of this.
> And for
> Designers, something more tangible like the User-Guide doc.
yes, but this issue is tangental to what i was talking about.
...
> Developers need to know:
...
> Designers need to know:
...
agreed. but again, the point of this thread was not the content but the
*format,* and that with regards to documenting each individual tool. if you
do not (as you seemed to indicate above) like either Gabe's format or javadoc
for such purposes, can you explain better what you have in mind instead?
Nathan Bubna
nathan@esha.com
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
RE: [veltools] Tool documentation
Posted by "Marinó A. Jónsson" <ma...@centrum.is>.
Well put, Timo. I agree.
cheers,
Marinó
> -----Original Message-----
> From: Tim Colson [mailto:tcolson@cisco.com]
> Sent: 9. nóvember 2003 20:22
> To: 'Velocity Developers List'
> Subject: RE: [veltools] Tool documentation
>
>
> Nathan asked:
> > I'd like to know if people still see this dvsl
> > documentation of tools as really useful and
> > worth the significant effort it
>
> -1
> (I appreciate that Gabe created docs, but I think the content
> could be presented more plainly for users.)
>
> -1 on Nathan's suggestion to ONLY use Javadoc.
>
> Why? I think we have two audiences (Developers & Designers)
> and believe each need different documentation. I think we
> could create for Developers a single-page doc on tools and
> configuration. And for Designers, something more tangible
> like the User-Guide doc.
>
> Cheers,
> Timo
>
> ------
> Developers need to know:
> <tool>
> <key>msg</key>
> <scope>request</scope>
> <class>org.apache.velocity.tools.struts.MessageTool</class>
> </tool>
>
> Designers need to know:
> ----
> Struts provides localization of 'messages' using a message
> resource file. It can also substitute up to five 'replacement
> parameters' into the message.
>
> Assuming that the message resource files contain the
> following messages:
>
> title=Welcome to Velocity for Struts
> test=This message has five replacement parameters: {0}, {1},
> {2}, {3}, {4}
>
> then the following Velocity script:
>
> $msg.get("title")
> $msg.title
> $msg.get("test", ["bear", "wolf", "tiger"])
>
> produces this output:
>
> Welcome to Velocity for Struts
> Welcome to Velocity for Struts
> This message has five replacement parameters: bear, wolf,
> tiger, {3}, {4}
> -----
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
RE: [veltools] Tool documentation
Posted by Tim Colson <tc...@cisco.com>.
Nathan asked:
> I'd like to know if people still see this dvsl
> documentation of tools as really useful and
> worth the significant effort it
-1
(I appreciate that Gabe created docs, but I think the content could be
presented more plainly for users.)
-1 on Nathan's suggestion to ONLY use Javadoc.
Why? I think we have two audiences (Developers & Designers) and believe
each need different documentation. I think we could create for
Developers a single-page doc on tools and configuration. And for
Designers, something more tangible like the User-Guide doc.
Cheers,
Timo
------
Developers need to know:
<tool>
<key>msg</key>
<scope>request</scope>
<class>org.apache.velocity.tools.struts.MessageTool</class>
</tool>
Designers need to know:
----
Struts provides localization of 'messages' using a message resource
file. It can also substitute up to five 'replacement parameters' into
the message.
Assuming that the message resource files contain the following messages:
title=Welcome to Velocity for Struts
test=This message has five replacement parameters: {0}, {1}, {2}, {3},
{4}
then the following Velocity script:
$msg.get("title")
$msg.title
$msg.get("test", ["bear", "wolf", "tiger"])
produces this output:
Welcome to Velocity for Struts
Welcome to Velocity for Struts
This message has five replacement parameters: bear, wolf, tiger, {3},
{4}
-----
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org