forrest-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Linda Rose" <lindar...@cox.net>
Subject Re: Improving documentation - you can help! (was Re: modifying the css for forrest)
Date Thu, 04 Nov 2004 23:09:19 GMT
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" <rgardler@apache.org>
To: <user@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
> 



Mime
View raw message