Re: documentation additions and issue tracking

[David Crossley <cr...@apache.org>]

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. 

In my opinion a set of HowTo docs would be best. Each one would be
very concise, concentrating on specific topics. Some examples:

* Install Forrest on Windows.
... very specific instructions, no mention of UNIX, specific example
pathnames and environment settings. Another section of the doc could
mention variations for older version of Windows.

* Using Forrest in dynamic mode.
... Show how to create a new directory, do 'forrest seed', start
the dynamic forrest, and begin the edit/review cycle.

* Building a set of static documents.
... Show how to do 'forrest site', explain where the documents are
generated, how to view them, how to zip, them up and unpack on a
webserver.

* Interpreting the Forrest output messages.
... Explain the purpose of the output messages from running
forrest, show some specific messages to be aware of.


Each document would refer to other HowTo docs in the Prerequisites
section. That way there are tracks of documents.

If some tasks are very specific and would be linked to from various
other documents, then these should be FAQs.

It is hard to know when a doc should be complete Howto, or when to
use multiple Howtos, or when a main doc is better. There is recent
discussion in the forrest-dev mail archives which might help:
http://marc.theaimsgroup.com/?l=forrest-dev&m=111165685011990
(Start there and go forward.)

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

At this stage of Forrest we need more developers and especially ones
who are determined to understand the guts, so we don't yet go out
of our way to attract users. Our developer community is still small,
so it would be harder to provide support. People starting to help with
the docs, such as you, is a brilliant point to reach.

That said, of course we need beginner documentation and we need it now.
By the time we do get a rush of new users, we will have good supporting
docs. Getting people started quickly is very important, and it means
that we can save time and get on with answering more advanced questions
and more development. Such documentation helps everyone, including new
developers.

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