forrest-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Maurice Lanselle <>
Subject Re: documentation additions and issue tracking (Was: App vs Data)
Date Sat, 28 May 2005 18:27:24 GMT
Phil Sullivan said the following on 28/05/2005 16:30:

> 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 agree.  After I started playing with the colors of the pelt skin, I 
was intrigued by the way level-2-tabs (are supposed to) work and which 
menu items get assigned to each tab.  I checked both the 0.6 and the 0.7 
doc on menus.
a) subtabs are not mentioned.
b) there is an explanation of an example site.xml and tabs.xml showing 
what the result is, but it leaves a lot of unanswered questions for 
someone who wants a different result.  Like, can you have multiple <faq 
 > elements as long as they have different labels, or should you call 
them <faq1 >, <faq2 >, etc?  Are you allowed to call them <faq1 >, <faq2

 >, etc or are the tags in menus constrained by a DTD?  Same question 
for groupings of elements.

So I fully agree that how-to manage the navigation experience and how-to 
go beyond modifying template content is needed.

> 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 i 
> went withthe default.
*someone else* here: tigris seems to work and I like its less colorful 
look, but leather-dev seems to look like pelt but with the menu in the 
middle of the page.
But even in *basic* skin use, for example, a project name longer than 
"MyProject" can cause appearance problems, and there are not many clues 
on what to do about it:  we need an explanation of how-to adjust if your 
project logo doesn't fit in the default settings (I sketched that in my 
first post here and will rework it if necessary.) Oh, and it took me 
longer than it should to find the how-to.xml template in the 
distribution--I was only looking in the seeded project for useable 
templates! Nobody told me...

> 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?
I agree.  The seeded site is a great demo, and a good start for the 
curious.  But what do you do after 'forrest run' and you've finished 
playing with the demo?  How do you kill jetty?  Reboot?  ;-) Seriously, 
you shouldn't tell people how to start something and not how to finish it.

I think a collection of HowTo's makes sense, or call it an "Owner's 
Manual", like you get with a new car--something that might eventually 
become tutorials as well. And with links from them to the 
*Documentation* documentation to "learn more".

>> 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

I totally agree with your assessment of challenges many potential users 
face.  I have trouble imagining my father using Forrest, yet he has 
built his own static website editing html templates with Notepad or 
Word. Does everyone have a JRE installed?  Is that requirement mentioned 

Furthermore, I hate backslashes, too.  I have written a bat file to ease 
my most common move: "cd c:\documents and settings\all 
users\documents\www\myproject".  And thanks to Forrest, I finally 
learned how to set environment variables in Win XP.

I'll be glad to participate (but don't know how to use svn). 


View raw message