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!

[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