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 [EMAIL PROTECTED] --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
