Improving documentation - you can help! (was Re: modifying the css for forrest)

[Ross Gardler <rg...@apache.org>]

Clay Leeds wrote:
> On Nov 4, 2004, at 12:04 PM, Ross Gardler wrote:
> 
>> Linda Rose wrote:

<snip/>

 > > > As per the instructions, I copied the pelt skins to
 > > > myproject/src/documentation/skins/mypelt and modified the line in
 > > > forrest.properties project.skin=src/documentation/skins/mypelt.
 > >
 > > That should be just "mypelt".
 >
> I'm pretty sure Ross meant that the line in forrest.properties should be 
> just:
> 
> project.skin=mypelt

Yes, that is what I meant

> 
> <rant>
> I get confused in the Forrest docs where assumptions are made by the 
> author, and I just don't get it. It's particularly frustrating, when I'm 
> close to a solution, but the amount of time to resolve a problem is 
> exacerbated by little assumptions like this

Hmmmm...

I'm not sure you can call it a tiny assumption when the doc originally 
referenced says:

"For example, copy forrest/src/core/context/skins/pelt  to your project 
area at src/documentation/skins/my-fancy-skin and add 
project.skin=my-fancy-skin to forrest.properties"

In this sentence, it clearly says what to put in the property (note the 
"project.skin=my-fancy-skin") on the last line.

That being said, our docs *do* need improvement. The problem is that the 
people working on the code are doing so on a voluntary basis, we don't 
get paid (at least not directly) for this work, and we certainly don't 
get paid to write documentation. It is a common problem for Open source 
projects, but you, as users, can help (read on).

> One of my goals is to improve FOPs documentation (and Forrest's as I 
> slog through the process of getting FOP's docs back online!) so that 
> newbies like myself don't have to deal with silly frustrations like 
> this. IMO, documentation should not skimp on examples. Rather, they 
> should almost go out of their way to be verbose.

Speaking personally, I do not have the time to write extensive examples 
- my code *is* my example, unfortunatley this creates a particularly 
high barrier to entry, that's why I am spending the free time I have 
between contracts helping out here on the user list, as well as writing 
code improvements in the core of Forrest - work which I will eventually 
get paid for. So how can users, help?

It would be really nice if people who get helped out on the user lists 
could help improve the project by clarifying things that confused them 
in the docs. As Clay says adding examples and notes from your experience 
can help a great deal.

Contributing to a project like this one does not only mean writing code. 
Docs and assisting fellow users on this list are equally as valuable.

To contribute your documentation enhancements edit the relevant files 
and commit a diff to the issue tracker ( 
http://issues.cocoondev.org/secure/BrowseProject.jspa?id=10000 ). If you 
don't know how to create a diff see 
http://forrest.apache.org/contrib.html If you still can't prepare a diff 
(that document probably needs some improving too) then posting your 
notes/examples and an explanation of where they fit into the 
documentation to an issue is the next best thing.

Every small contribution helps a great deal, please give back to the 
project when your personal schedule allows.

> </rant>
> 
> NOTE: The above rant wasn't directed 'at' Ross (or anyone in 
> particular). ;-)

Neither was my response aimed at Clay (or anyone in particular) ;-)

Ross

Re: Improving documentation - you can help!

[Ross Gardler <rg...@apache.org>]

Clay Leeds wrote:
> Ross Gardler said:

<snip/>

>>That being said, our docs *do* need improvement. The problem is that the
>>people working on the code are doing so on a voluntary basis, we don't
>>get paid (at least not directly) for this work, and we certainly don't
>>get paid to write documentation. It is a common problem for Open source
>>projects, but you, as users, can help (read on).
> 
> 
> And for that, I thank you. I apologize for the tone of my message (I guess
> it's never really a good idea to prefix something with <rant> ;-)). I
> guess I could just continue along <quietly/> contributing little PATCHes
> here and there (as I've started doing over the last few days...).

Yes, you have started contributing patches (actually you have been doing 
for a long time, and you have also been active on the lists for a long 
time - also a contribution to Forrest). I simply replied in order to say 
that others can do it too.

Please *don't* continue quietly, by saying what needs to be done you 
make us *all* aware. People often want to help but don't know how. Your 
rant pointed out one way *everyone* can help.

Ross

Re: Improving documentation - you can help!

[Clay Leeds <cl...@medata.com>]

Ross Gardler said:
> Hmmmm...
>
> I'm not sure you can call it a tiny assumption when the doc originally
> referenced says:
>
> "For example, copy forrest/src/core/context/skins/pelt  to your project
> area at src/documentation/skins/my-fancy-skin and add
> project.skin=my-fancy-skin to forrest.properties"
>
> In this sentence, it clearly says what to put in the property (note the
> "project.skin=my-fancy-skin") on the last line.

D'oh! Thanks for pointing that out! Sorry for wasting more of your time.

> That being said, our docs *do* need improvement. The problem is that the
> people working on the code are doing so on a voluntary basis, we don't
> get paid (at least not directly) for this work, and we certainly don't
> get paid to write documentation. It is a common problem for Open source
> projects, but you, as users, can help (read on).

And for that, I thank you. I apologize for the tone of my message (I guess
it's never really a good idea to prefix something with <rant> ;-)). I
guess I could just continue along <quietly/> contributing little PATCHes
here and there (as I've started doing over the last few days...).

>> One of my goals is to improve FOPs documentation (and Forrest's as I
>> slog through the process of getting FOP's docs back online!) so that
>> newbies like myself don't have to deal with silly frustrations like
>> this. IMO, documentation should not skimp on examples. Rather, they
>> should almost go out of their way to be verbose.
>
> Speaking personally, I do not have the time to write extensive examples
> - my code *is* my example, unfortunatley this creates a particularly
> high barrier to entry, that's why I am spending the free time I have
> between contracts helping out here on the user list, as well as writing
> code improvements in the core of Forrest - work which I will eventually
> get paid for. So how can users, help?
>
> It would be really nice if people who get helped out on the user lists
> could help improve the project by clarifying things that confused them
> in the docs. As Clay says adding examples and notes from your experience
> can help a great deal.
>
> Contributing to a project like this one does not only mean writing code.
> Docs and assisting fellow users on this list are equally as valuable.
>
> To contribute your documentation enhancements edit the relevant files
> and commit a diff to the issue tracker (
> http://issues.cocoondev.org/secure/BrowseProject.jspa?id=10000 ). If you
> don't know how to create a diff see
> http://forrest.apache.org/contrib.html If you still can't prepare a diff
> (that document probably needs some improving too) then posting your
> notes/examples and an explanation of where they fit into the
> documentation to an issue is the next best thing.
>
> Every small contribution helps a great deal, please give back to the
> project when your personal schedule allows.

Thanks! I'll see what I can do to improve the docs where I find vagaries.

>> </rant>
>>
>> NOTE: The above rant wasn't directed 'at' Ross (or anyone in
>> particular). ;-)
>
> Neither was my response aimed at Clay (or anyone in particular) ;-)
>
> Ross

Again, I apologize for my tone and for wasting time.

--
Clay Leeds - cleeds@medata.com
Web Developer - Medata, Inc. - http://www.medata.com
PGP Public Key: https://mail.medata.com/pgp/cleeds.asc

Re: Improving documentation - you can help! (was Re: modifying the css for forrest)

[Ross Gardler <rg...@apache.org>]

Linda Rose wrote:
> I had tried it first as project.skin=mypelt and got an error message 
> with that too. So I tried it with the path included. Sorry for any 
> confusion.

No problem, we are here to help :-)

I'm not sure if you have got it working yet or not. If not then please 
respond to the original mail as I changes the subject on this one to 
reflect the fact it was dealing with Clay's comments on documentation.

Ross

Re: Improving documentation - you can help! (was Re: modifying the css for forrest)

[Linda Rose <li...@cox.net>]

I had tried it first as project.skin=mypelt and got an error message with 
that too. So I tried it with the path included. Sorry for any confusion.


----- Original Message ----- 
From: "Ross Gardler" <rg...@apache.org>
To: <us...@forrest.apache.org>
Sent: Thursday, November 04, 2004 1:50 PM
Subject: Improving documentation - you can help! (was Re: modifying the css 
for forrest)


> Clay Leeds wrote:
>> On Nov 4, 2004, at 12:04 PM, Ross Gardler wrote:
>>
>>> Linda Rose wrote:
>
> <snip/>
>
> > > > As per the instructions, I copied the pelt skins to
> > > > myproject/src/documentation/skins/mypelt and modified the line in
> > > > forrest.properties project.skin=src/documentation/skins/mypelt.
> > >
> > > That should be just "mypelt".
> >
>> I'm pretty sure Ross meant that the line in forrest.properties should be 
>> just:
>>
>> project.skin=mypelt
>
> Yes, that is what I meant
>
>>
>> <rant>
>> I get confused in the Forrest docs where assumptions are made by the 
>> author, and I just don't get it. It's particularly frustrating, when I'm 
>> close to a solution, but the amount of time to resolve a problem is 
>> exacerbated by little assumptions like this
>
> Hmmmm...
>
> I'm not sure you can call it a tiny assumption when the doc originally 
> referenced says:
>
> "For example, copy forrest/src/core/context/skins/pelt  to your project 
> area at src/documentation/skins/my-fancy-skin and add 
> project.skin=my-fancy-skin to forrest.properties"
>
> In this sentence, it clearly says what to put in the property (note the 
> "project.skin=my-fancy-skin") on the last line.
>
> That being said, our docs *do* need improvement. The problem is that the 
> people working on the code are doing so on a voluntary basis, we don't get 
> paid (at least not directly) for this work, and we certainly don't get 
> paid to write documentation. It is a common problem for Open source 
> projects, but you, as users, can help (read on).
>
>> One of my goals is to improve FOPs documentation (and Forrest's as I slog 
>> through the process of getting FOP's docs back online!) so that newbies 
>> like myself don't have to deal with silly frustrations like this. IMO, 
>> documentation should not skimp on examples. Rather, they should almost go 
>> out of their way to be verbose.
>
> Speaking personally, I do not have the time to write extensive examples - 
> my code *is* my example, unfortunatley this creates a particularly high 
> barrier to entry, that's why I am spending the free time I have between 
> contracts helping out here on the user list, as well as writing code 
> improvements in the core of Forrest - work which I will eventually get 
> paid for. So how can users, help?
>
> It would be really nice if people who get helped out on the user lists 
> could help improve the project by clarifying things that confused them in 
> the docs. As Clay says adding examples and notes from your experience can 
> help a great deal.
>
> Contributing to a project like this one does not only mean writing code. 
> Docs and assisting fellow users on this list are equally as valuable.
>
> To contribute your documentation enhancements edit the relevant files and 
> commit a diff to the issue tracker ( 
> http://issues.cocoondev.org/secure/BrowseProject.jspa?id=10000 ). If you 
> don't know how to create a diff see http://forrest.apache.org/contrib.html 
> If you still can't prepare a diff (that document probably needs some 
> improving too) then posting your notes/examples and an explanation of 
> where they fit into the documentation to an issue is the next best thing.
>
> Every small contribution helps a great deal, please give back to the 
> project when your personal schedule allows.
>
>> </rant>
>>
>> NOTE: The above rant wasn't directed 'at' Ross (or anyone in particular). 
>> ;-)
>
> Neither was my response aimed at Clay (or anyone in particular) ;-)
>
> Ross
>