forrest-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <rgard...@apache.org>
Subject Improving documentation - you can help! (was Re: modifying the css for forrest)
Date Thu, 04 Nov 2004 21:50:58 GMT
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

Mime
View raw message