You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@velocity.apache.org by Brett Sutton <bs...@idatam.com.au> on 2004/06/07 00:47:19 UTC
User Documentation
I would like to suggest that while all of this wiki activity is underway
that we move the user and developer documentation into the wiki as well.
The logic is that if the doco was wikified (is that a word?) then more
people could contribute to its upkeep, such as fixing errors, adding
examples and annotations etc.
I've wanted to change the doco on a number of occasions but it just seemed
too hard to submit a change request. If it was wikified then I would have
just gone in and modified it.
That's my opinion anyway.
Regards,
S. Brett Sutton.
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
RE: User Documentation
Posted by Tim Colson <tc...@cisco.com>.
Catching up after 10 days of being Off the Grid & Net riding my bike 600
miles from SF to LA....
> > that we move the user and developer documentation into the wiki as
-1
( If it was a Confluence wiki, I might be +1 --> because pages/wiki topics
can be arranged into a heirarchy and exported as a group to PDF/XML/HTML. )
I agree with Geir and others, even though my bandwidth is cheap, I always
want to be able to take it with me (we don't have broadband on the plane, or
in the car... yet). In fact, I have a few ideas for improvements to the
current User/Dev Guides to make them more easily readable offline, printed,
and on a Palm.
Cheers,
Timo
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: User Documentation
Posted by Will Glass-Husain <wg...@forio.com>.
I reference local help for Velocity and similar projects from time to time
(train & plane time, for example).
There must be some way of extracting the Wiki. Hibernate does this for
example. (Wiki docs, but they all are included in the download). Not the
same software, I know, but perhaps we could figure this out.
WILL
----- Original Message -----
From: "Brett Sutton" <bs...@idatam.com.au>
To: "'Velocity Developers List'" <ve...@jakarta.apache.org>
Sent: Sunday, June 06, 2004 5:45 PM
Subject: RE: User Documentation
> First problem is I've no idea how to post a patch, and yes I could learn,
> but so would everyone else that wants to update the docs and it's just one
> more hurdle to get over (plus I'm a lazy git).
>
> As to the HTML ball, I assume you want to do that to deploy help. I just
> wonder how many people are referencing local help these days. I for one
> always go straight to the web site. It might be worth doing some sort of
> survey to see how important it is.
>
> Having said that a method of creating a HTML extract from a wiki would be
> nice.
>
> Regards,
> Brett.
> -----Original Message-----
> From: Geir Magnusson Jr [mailto:geir@4quarters.com]
> Sent: Monday, 7 June 2004 9:07 AM
> To: Velocity Developers List
> Subject: Re: User Documentation
>
>
> On Jun 6, 2004, at 6:47 PM, Brett Sutton wrote:
>
> > I would like to suggest that while all of this wiki activity is
> > underway
> > that we move the user and developer documentation into the wiki as
> > well.
> >
> > The logic is that if the doco was wikified (is that a word?) then more
> > people could contribute to its upkeep, such as fixing errors, adding
> > examples and annotations etc.
>
> The problem I have w/ wikification (I have lots of problems,
> actually...) is that you can't take it with you. IOW, you have to be
> connected.
>
> >
> > I've wanted to change the doco on a number of occasions but it just
> > seemed
> > too hard to submit a change request. If it was wikified then I would
> > have
> > just gone in and modified it.
>
> Why? Just post the patch to the docs.
>
> >
> > That's my opinion anyway.
>
> I know a few people are working on extracting the docs out of wiki into
> an HTML ball that we could include. That would solve one of the big
> drawbacks of wiki (IMO) if we did the same thing.
>
> geir
>
> >
> > Regards,
> > S. Brett Sutton.
> >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
> > For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
> >
> >
> --
> Geir Magnusson Jr 203-247-1713(m)
> geir@4quarters.com
>
>
> ---------------------------------------------------------------------
> 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
>
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
RE: User Documentation
Posted by Brett Sutton <bs...@idatam.com.au>.
Daniel Dekany said:
> Some people has no Internet connection at all; if they need Internet,
> then they have to go to the nearest "Internet Cafe", or into the college
valid point.
-----Original Message-----
From: Daniel Dekany [mailto:ddekany@freemail.hu]
Sent: Monday, 7 June 2004 8:53 PM
To: Velocity Developers List
Subject: Re: User Documentation
Monday, June 7, 2004, 2:45:04 AM, Brett Sutton wrote:
> First problem is I've no idea how to post a patch, and yes I could learn,
> but so would everyone else that wants to update the docs and it's just one
> more hurdle to get over (plus I'm a lazy git).
>
> As to the HTML ball, I assume you want to do that to deploy help. I just
> wonder how many people are referencing local help these days. I for one
> always go straight to the web site. It might be worth doing some sort of
> survey to see how important it is.
Some people has no Internet connection at all; if they need Internet,
then they have to go to the nearest "Internet Cafe", or into the college
or other workplace, ...etc, and download the stuff (like Velocity
tar.gz) to a floppies. Then, many people has dial-in Internet connection
(56Kbit/s...), and they have to pay bill for each minutes while they are
connected, also they may have to pay a fix price for each successful
dialing, also they may have a maximum connection time per month. In this
case, you connect, quickly download what you want to the HDD, and
disconnect. And you want to repeat this as seldom as possible. So you
can not use on-line documentation.
The point is that, I guess, people with connection problems are
typically not subscribers to mailing lists, so the survey will not show
the real percentage. And, perhaps they are few in percentage (since
there are fewer programmers in countries with weak IT)... I don't
know... but personally, I feel bad about ignoring people who lives in
those least rich countries.
(And of course, even if you are a wealthy man, if you have to travel a
lot with your laptop on train or airplane, where you don't have Internet
connection... OK, that's a small percentage again.)
> Having said that a method of creating a HTML extract from a wiki would be
> nice.
(As a least chance, there are downloaders that "spider" sites and
download them for off-line reading. Somebody do a snap-shoot with a such
downloader periodically, and tar.gz the result...)
--
Best regards,
Daniel Dekany
---------------------------------------------------------------------
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: User Documentation
Posted by Daniel Dekany <dd...@freemail.hu>.
Monday, June 7, 2004, 2:45:04 AM, Brett Sutton wrote:
> First problem is I've no idea how to post a patch, and yes I could learn,
> but so would everyone else that wants to update the docs and it's just one
> more hurdle to get over (plus I'm a lazy git).
>
> As to the HTML ball, I assume you want to do that to deploy help. I just
> wonder how many people are referencing local help these days. I for one
> always go straight to the web site. It might be worth doing some sort of
> survey to see how important it is.
Some people has no Internet connection at all; if they need Internet,
then they have to go to the nearest "Internet Cafe", or into the college
or other workplace, ...etc, and download the stuff (like Velocity
tar.gz) to a floppies. Then, many people has dial-in Internet connection
(56Kbit/s...), and they have to pay bill for each minutes while they are
connected, also they may have to pay a fix price for each successful
dialing, also they may have a maximum connection time per month. In this
case, you connect, quickly download what you want to the HDD, and
disconnect. And you want to repeat this as seldom as possible. So you
can not use on-line documentation.
The point is that, I guess, people with connection problems are
typically not subscribers to mailing lists, so the survey will not show
the real percentage. And, perhaps they are few in percentage (since
there are fewer programmers in countries with weak IT)... I don't
know... but personally, I feel bad about ignoring people who lives in
those least rich countries.
(And of course, even if you are a wealthy man, if you have to travel a
lot with your laptop on train or airplane, where you don't have Internet
connection... OK, that's a small percentage again.)
> Having said that a method of creating a HTML extract from a wiki would be
> nice.
(As a least chance, there are downloaders that "spider" sites and
download them for off-line reading. Somebody do a snap-shoot with a such
downloader periodically, and tar.gz the result...)
--
Best regards,
Daniel Dekany
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
RE: User Documentation
Posted by Brett Sutton <bs...@idatam.com.au>.
First problem is I've no idea how to post a patch, and yes I could learn,
but so would everyone else that wants to update the docs and it's just one
more hurdle to get over (plus I'm a lazy git).
As to the HTML ball, I assume you want to do that to deploy help. I just
wonder how many people are referencing local help these days. I for one
always go straight to the web site. It might be worth doing some sort of
survey to see how important it is.
Having said that a method of creating a HTML extract from a wiki would be
nice.
Regards,
Brett.
-----Original Message-----
From: Geir Magnusson Jr [mailto:geir@4quarters.com]
Sent: Monday, 7 June 2004 9:07 AM
To: Velocity Developers List
Subject: Re: User Documentation
On Jun 6, 2004, at 6:47 PM, Brett Sutton wrote:
> I would like to suggest that while all of this wiki activity is
> underway
> that we move the user and developer documentation into the wiki as
> well.
>
> The logic is that if the doco was wikified (is that a word?) then more
> people could contribute to its upkeep, such as fixing errors, adding
> examples and annotations etc.
The problem I have w/ wikification (I have lots of problems,
actually...) is that you can't take it with you. IOW, you have to be
connected.
>
> I've wanted to change the doco on a number of occasions but it just
> seemed
> too hard to submit a change request. If it was wikified then I would
> have
> just gone in and modified it.
Why? Just post the patch to the docs.
>
> That's my opinion anyway.
I know a few people are working on extracting the docs out of wiki into
an HTML ball that we could include. That would solve one of the big
drawbacks of wiki (IMO) if we did the same thing.
geir
>
> Regards,
> S. Brett Sutton.
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
>
>
--
Geir Magnusson Jr 203-247-1713(m)
geir@4quarters.com
---------------------------------------------------------------------
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: User Documentation
Posted by Geir Magnusson Jr <ge...@4quarters.com>.
On Jun 6, 2004, at 6:47 PM, Brett Sutton wrote:
> I would like to suggest that while all of this wiki activity is
> underway
> that we move the user and developer documentation into the wiki as
> well.
>
> The logic is that if the doco was wikified (is that a word?) then more
> people could contribute to its upkeep, such as fixing errors, adding
> examples and annotations etc.
The problem I have w/ wikification (I have lots of problems,
actually...) is that you can't take it with you. IOW, you have to be
connected.
>
> I've wanted to change the doco on a number of occasions but it just
> seemed
> too hard to submit a change request. If it was wikified then I would
> have
> just gone in and modified it.
Why? Just post the patch to the docs.
>
> That's my opinion anyway.
I know a few people are working on extracting the docs out of wiki into
an HTML ball that we could include. That would solve one of the big
drawbacks of wiki (IMO) if we did the same thing.
geir
>
> Regards,
> S. Brett Sutton.
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
>
>
--
Geir Magnusson Jr 203-247-1713(m)
geir@4quarters.com
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org