forrest-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Clay Leeds" <cle...@medata.com>
Subject Re: Improving documentation - you can help!
Date Thu, 04 Nov 2004 22:48:46 GMT
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



Mime
View raw message