forrest-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Phil Sullivan <pas...@rcn.com>
Subject Re: documentation additions and issue tracking (Was: App vs Data)
Date Sat, 28 May 2005 14:30:40 GMT
 To help with the beginner definition, my experience may be useful.

I was attracted to Forrest precisely because i know *nothing* about CSS 
. My html skills are very basic, although perhaps better than a typical 
newbie. On the other hand my Command line, and O/S skills in both 
windows and *nix environments is extensive.

The attraction was that after some effort at learning how to use the 
templates and XML (which I also knew nothing about)  i was able to spin 
off a nicely formated web page....with really no development work - just 
changing content from the seed site to my own.  My intention is that 
over time as I learn how forrest works I would gradually customize the 
site - but it was a quick way to hammer out a basic site to start.

What would have (and would be :-))  useful for me was clearer doc's 
around the tabbing structure. I got it working through trial and error. 
A real newbie might not be willing to do that. I also had a hard time 
getting my head around where static html pages should go ...(i.e an 
existing html page outputed from say word or open office).

Finally i never was able to figure out how to use other skins (which 
someone else brought up recently). This was not important to me...so i 
went withthe default.

If it would be useful I would be willing to help with the documentation 
effort by reviewing it from the perspective of a person with limited 
knowledge of css, xml, or forrest ....

Phil

Addi wrote:

> ** (from users, brought over to dev - replies will go to dev) **
> Brought this over to dev to continue the discussion on exactly how to 
> proceed with beginner documetation.  As David points out we should 
> figure out  whether this is something that should be a separate HowTo, 
> incorporated into the main docs or something else.
> Originally I was thinking of it as a HowTo and that we could take some 
> of the more important bits and add them to the main docs.  But I do 
> think (actually hope) that the average user skills will decrease as 
> forrest spreads.  Right now it feels very geeky and I have friends who 
> know something about html and css who may be interested in a program 
> like this but would't really be able to pull this off with their 
> current knowledge and, frankly, aren't going to take time to figure it 
> out.  If we want to bring more folks like that into the fold, then 
> maybe moving more of the basic stuff into the main docs would make 
> more sense.  WDYT?
>
> To clarify a little what I mean by beginner, I am starting with as few 
> assumptions as I think reasonable.  The perspective is someone who 
> uses html and css, probably using a GUI editor, has no command line 
> experience and can follow directions :).  Most linux users have some 
> command line experience but from linux forums I can see lots of new to 
> linux users who don't really grasp it beyond the specific thing they 
> are told to type in an answer to their question.  Most windows users 
> don't have any of it.  I use it all the time on my linux/unix boxes 
> but forrest is the first time I had to figure any of it out in windows 
> (I now hate backslashes in a whole new way).
>
> -Addi
>
> David Crossley wrote:
>
>> Addi wrote:
>>  
>>
>>> I am planning on working on beginner, step by step type 
>>> documentation over time (as I learn the answers to my own questions).
>>>   
>>
>>
>> It would be best if we created a shell of a new document
>> so that you and any others can work on it together.
>> More below about that ...
>>
>>  
>>
>>> I was wondering if it would be OK to start a new issue in JIRA for 
>>> an improvement in docs on this.  That way, as people see problems 
>>> that new users are having in the lists, we can add them to the list 
>>> of those issues in JIRA to make it easier to keep track of it.  Is 
>>> that appropriate or is there another system set up for something 
>>> like this?  I feel that keeping my own scratchpad of issues is not 
>>> terribly efficient, since I don't know all the issues ...
>>>   
>>
>>
>> This sounds like a good idea. I recommend separate issues
>> for each item. After we have incorporated that piece into
>> the documentation, then we close the issue. There is a category
>> for "Documentation". Give each issue a useful Summary title.
>> Keep the Description concise, and use Comments for more detail.
>> Link to mail list discussions where appropriate.
>>
>> Are you working with the head of development, i.e. the
>> trunk of SVN?
>>
>>  
>>
>>> ... and it would suck for myself and someone else to be writing docs 
>>> on the same issue at the same time, thereby wasting someone's time.
>>>   
>>
>>
>> That is exactly why we try to work on every document
>> in the SVN repository. It is then collaborative.
>>
>> It is also good practice to do it bit by bit, i.e.
>> progressively build the document rather than do a
>> whole swag by yourself, only to find that when it
>> comes time for us to commit the work, that you
>> have gone off track.
>>
>> Remember too, that it is quite okay to have
>> "Fixme:" banners inside the published docs.
>>
>> It would probably be useful to discuss the overall aim
>> of this beginners documentation. Will it be one document
>> in the main section of the website, will it be a HowTo.
>> That sort of discussion is more appropriate for the
>> dev mailing list.
>>
>> This is exciting, thanks for helping out.
>>
>> --David
>>
>>  
>>
>>> What do you all recommend/already have in place?
>>>
>>> Thanks
>>> Addi
>>>
>>>
>>> Ross Gardler wrote:
>>>
>>>   
>>>
>>>> Tim Williams wrote:
>>>>
>>>>     
>>>>
>>>>> Embarrassingly enough, I was having a difficult time understanding 
>>>>> the
>>>>> much simpler multiple statically built sites with one Forrest.  Ross'
>>>>> answer was helpful and I think my problem was that I never created a
>>>>> subdirectory to do the seed in so that I had a single "src" at a
>>>>> higher level than it should have been.  Having the 
>>>>> "mkdir->cd->forrest
>>>>> see" and maybe a little explanation of having "multiple sites" would
>>>>> be helpful somewhere.
>>>>>
>>>>>       
>>>>
>>>> We would love a patch for the docs making this clearer, sometimes 
>>>> we forget these critical points that are less obvious than we 
>>>> assume them to be.
>>>>
>>>> Ross
>>>>     
>>>
>>
>>
>>
>>  
>>
>
>


Mime
View raw message