forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Addi <a...@rocktreesky.com>
Subject Re: vague issues with Forrest use
Date Mon, 31 Oct 2005 14:53:23 GMT
Ross Gardler wrote:

> Addi wrote:
>
>> Hm, well I don't know what resources the Apache projects are dealing
>> with but I have not implemented Forrest at my work (other than for me
>> to play with) because I am the only person who understands anything
>> about XML.  The biggest hurdles I see at my office are site.xml and
>> the actual documents with deployment also being a secondary issue. 
>> They are hurdles because I can't be the only person who knows how to
>> use it.  It isn't efficient if I'm the only one who can add docs and
>> do anything at all with it.  Now that I have spent time with Forrest
>> I know there are some tools to help me with those issues.  So *for my
>> use case situation* things that would make Forrest more viable:
>>
>> - A simple, intuitive way for non-XMLers to add things to site.xml
>
>
> Have you any suggestions about what this may look like?

No, unfortunately I haven't thought too hard on it and I have limited
coding skills to even know what can be done.  I just know that as soon
as I try to explain to coworkers how I add things their eyes sort of
glaze and they wander off to do something else.

>
> Have you taken a look at the Eclipse plugin? This is a (very early
> development) of a GUI application for editing of things like site.xml.
> It works, but is a long way from perfect.

I have installed Eclipse but never seem to have time to play around with
it or our plugins.  We don't have any need for Eclipse so it doesn't fit
into any other work I do.  I'll try to make time to check it out.

>
> The biggest hurdle to its use is that it requires an Eclipse
> installation, although it is possible to build a standalone
> application for it.
>
>> - Emphasis and stupid clear instructions on document plugins
>> (DocBook, OpenOffice)
>> - Emphasis and stupid clear instructions on Forrestbot
>
> >
>
>> By stupid clear, I mean so that someone with little XML and Forrest
>> experience can understand at least half of what you are saying and
>> not be intimidated to at least try.
>
>
> Yes, docs are important and are the hardest things to create. The
> problem is that to write them you need to have the inclination to make
> them "stupid clear", unfortunately most of the devs don't have such a
> drive.
>
> All help is welcome, and newcomers to Forrest are in the best position
> to write these stupid clear docs - with help and guidance from the
> devs of course.
>
> Ross

Well I do have an itch for stupid clear docs.  I did submit the
beginnings (mostly completed) of stupid clear docs for installing
Forrest - FOR-699 (http://issues.apache.org/jira/browse/FOR-699).  The
way I envision documentation though is to actually have a cohesive,
comprehensive manual.  I know this has been talked about before on the
list and we were looking at perhaps really hammering this out at
ApacheCon in San Diego, but it looks like a documentathon may not really
happen since not many will make it (I'm now leaning towards not being
able to go either).

So perhaps, for those of us who are interested, we should start
discussing a larger plan for documentation and the creation of a new
user "Intro to Forrest" that is basic and step-by-step.  Of course this
kind of project can be tricky since Forrest dev moves so quickly. 
Anyway, as we move closer to 1.0 release we do need to make the docs
easier to use and understand for users who are brand new to the whole
concept of what Forrest does and how.

As for the two main things on docs I listed above, I still don't grasp
Forrestbot well enough to feel like I could write the docs well.  I can
make it work but I don't have the time to really understand what exactly
it is doing.  If you look at the Forrestbot doc we have now, I put in
lots of fix me's on things I don't get.



Mime
View raw message