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 <nb...@gmail.com> on 2006/03/06 06:58:09 UTC
dev vs user vs guides
i was just scanning the so-called "developer guide" on the website to
see what logging control properties were documented there, and i had a
tangential thought that never occured to me before.
the "user guide" and "developer guide" don't correlate to the
velocity-user and velocity-dev lists. so i think perhaps some of
those who post user questions to the dev list do so because they
relate to the "developer guide" on the website.
perhaps we should rename the guides on the website to prevent such
confusion. essentially, the "User Guide" teaches people how to write
templates in VTL. the "Developer Guide" teaches people how to develop
applications that use Velocity.
i haven't thought long about better names, but perhaps something along
the lines of:
User Guide -> How to Write Templates
Developer Guide -> How to Use Velocity
better name ideas are welcome...
and as a bonus thought: you could probably break the Developer Guide
into two guides, one more focused on using Velocity and another on the
configuration minutia (which is not even fully documented). then we
could have guides on: Writing Templates, Using Velocity,
Configuration Options.
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: dev vs user vs guides
Posted by Nathan Bubna <nb...@gmail.com>.
On 3/26/06, Henning P. Schmiedehausen <hp...@intermeta.de> wrote:
> "Nathan Bubna" <nb...@gmail.com> writes:
>
> >perhaps we should rename the guides on the website to prevent such
> >confusion. essentially, the "User Guide" teaches people how to write
> >templates in VTL. the "Developer Guide" teaches people how to develop
> >applications that use Velocity.
>
> >i haven't thought long about better names, but perhaps something along
> >the lines of:
>
> >User Guide -> How to Write Templates
> >Developer Guide -> How to Use Velocity
>
> >better name ideas are welcome...
>
> Nathan,
>
> these are excellent ideas. One of the first things that I did was to
> take stock of the existing docs and put them into a mind mapping
> tool. I can really recommend Freemind (freemind.sf.net) which is open
> source and free.
i'll have to check it out...
> >and as a bonus thought: you could probably break the Developer Guide
> >into two guides, one more focused on using Velocity and another on the
> >configuration minutia (which is not even fully documented). then we
> >could have guides on: Writing Templates, Using Velocity,
> >Configuration Options.
>
> Hm. I'd think that the developers guide should focus on "programming
> with Velocity" and the "how to configure Velocity" is basically an
> Appendix to it. One of the problems with many xdoc driven sites is,
> that documentation is spread out too thin over many pages.
yeah, i like the idea of the configuration section being an appendix.
it really is more of a reference/lookup-table then a tutorial-type
section. now, if i could only find some time to do this.... :)
> Best regards
> Henning
>
> --
> Dipl.-Inf. (Univ.) Henning P. Schmiedehausen INTERMETA GmbH
> hps@intermeta.de +49 9131 50 654 0 http://www.intermeta.de/
>
> RedHat Certified Engineer -- Jakarta Turbine Development -- hero for hire
> Linux, Java, perl, Solaris -- Consulting, Training, Development
>
> Social behaviour: Bavarians can be extremely egalitarian and folksy.
> -- http://en.wikipedia.org/wiki/Bavaria
> Most Franconians do not like to be called Bavarians.
> -- http://en.wikipedia.org/wiki/Franconia
>
> ---------------------------------------------------------------------
> 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: dev vs user vs guides
Posted by "Henning P. Schmiedehausen" <hp...@intermeta.de>.
"Nathan Bubna" <nb...@gmail.com> writes:
>perhaps we should rename the guides on the website to prevent such
>confusion. essentially, the "User Guide" teaches people how to write
>templates in VTL. the "Developer Guide" teaches people how to develop
>applications that use Velocity.
>i haven't thought long about better names, but perhaps something along
>the lines of:
>User Guide -> How to Write Templates
>Developer Guide -> How to Use Velocity
>better name ideas are welcome...
Nathan,
these are excellent ideas. One of the first things that I did was to
take stock of the existing docs and put them into a mind mapping
tool. I can really recommend Freemind (freemind.sf.net) which is open
source and free.
>and as a bonus thought: you could probably break the Developer Guide
>into two guides, one more focused on using Velocity and another on the
>configuration minutia (which is not even fully documented). then we
>could have guides on: Writing Templates, Using Velocity,
>Configuration Options.
Hm. I'd think that the developers guide should focus on "programming
with Velocity" and the "how to configure Velocity" is basically an
Appendix to it. One of the problems with many xdoc driven sites is,
that documentation is spread out too thin over many pages.
Best regards
Henning
--
Dipl.-Inf. (Univ.) Henning P. Schmiedehausen INTERMETA GmbH
hps@intermeta.de +49 9131 50 654 0 http://www.intermeta.de/
RedHat Certified Engineer -- Jakarta Turbine Development -- hero for hire
Linux, Java, perl, Solaris -- Consulting, Training, Development
Social behaviour: Bavarians can be extremely egalitarian and folksy.
-- http://en.wikipedia.org/wiki/Bavaria
Most Franconians do not like to be called Bavarians.
-- http://en.wikipedia.org/wiki/Franconia
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: dev vs user vs guides
Posted by Will Glass-Husain <wg...@forio.com>.
makes sense to me. We often beat up people for posting user questions to
the "developer's list" when it's only natural that they consider themselves
developers.
On 3/5/06, Nathan Bubna <nb...@gmail.com> wrote:
>
> i was just scanning the so-called "developer guide" on the website to
> see what logging control properties were documented there, and i had a
> tangential thought that never occured to me before.
>
> the "user guide" and "developer guide" don't correlate to the
> velocity-user and velocity-dev lists. so i think perhaps some of
> those who post user questions to the dev list do so because they
> relate to the "developer guide" on the website.
>
> perhaps we should rename the guides on the website to prevent such
> confusion. essentially, the "User Guide" teaches people how to write
> templates in VTL. the "Developer Guide" teaches people how to develop
> applications that use Velocity.
>
> i haven't thought long about better names, but perhaps something along
> the lines of:
>
> User Guide -> How to Write Templates
> Developer Guide -> How to Use Velocity
>
> better name ideas are welcome...
>
> and as a bonus thought: you could probably break the Developer Guide
> into two guides, one more focused on using Velocity and another on the
> configuration minutia (which is not even fully documented). then we
> could have guides on: Writing Templates, Using Velocity,
> Configuration Options.
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
>
>
--
_______________________________________
Forio Business Simulations
Will Glass-Husain
phone (415) 440-7500 x89
mobile (415) 235-4293
wglass@forio.com
www.forio.com