Mailing-List: contact general-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: general@incubator.apache.org
Received-SPF: pass (asf.osuosl.org: domain of mail@leosimons.com designates
 216.218.185.16 as permitted sender)
Date: Tue, 27 Dec 2005 07:50:50 -0800
From: Leo Simons <mail@leosimons.com>
To: general@incubator.apache.org
Cc: site-dev@apache.org
Subject: Re: [RT] Super Simple Site Generation Tool
Message-ID: <20051227155050.GB60941@bali.sjc.webweaving.org>
Mail-Followup-To: Leo Simons <mail@leosimons.com>,
	general@incubator.apache.org, site-dev@apache.org
References: <20051227140218.GA60941@bali.sjc.webweaving.org>
 <224f32340512270717w672a7e4v71ef30a4cac37636@mail.gmail.com>
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <224f32340512270717w672a7e4v71ef30a4cac37636@mail.gmail.com>
User-Agent: Mutt/1.4.2.1i

On Tue, Dec 27, 2005 at 04:17:37PM +0100, Thomas Dudziak wrote:
> since I'm rather new to this, I don't have a deep understanding of the
> problems you're trying to solve.

None is needed, the problem is very simple.

> However, to my naive understanding its two things:
> 
> * make the process of documenting incubated projects easier for their community
> * make the process of publishing this documentation easier (and more
> stable) for infra/incubator people

Actually its not for the incubated projects, just for the incubator
documentation and website itself. Each and every incubated project decides
what they want to do.

> Now I don't really know about the problems that you have with Forrest
> regarding the second point - it works for the projects that I work in,
> but then again we probably have fewer/simpler requirements. It would
> be nice if you could perhaps provide some details, e.g. regarding
> SVN-based publishing ?

Err, I would suggest you please go and read the general@incubator archives.
That's basically a "FAQ" at this point. You may also wish to go and look for
some posts by me over the last few years to the forrest mailing lists, or
to the avalon mailing lists with the added keyword of "forrest".

> Anyway, I think there are several possible things that could be done
> to deal with this (in the line of "eating your own dog food"), aside
> from implementing a new tool:
> 
> * Get Cocoon/Forrest developers to help in the Incubator.

We have a few actually. David Crossley is our "manual forrestbot" but it
doesn't scale. This is a bad idea. Everybody who knows SVN and how to
type in commands on a console should be able to manage the documentation
process end-to-end.

> * Simplify Forrest for 'admins'.

Yes its possible but it doesn't solve everything (its still going to be
big and complex and bloated and overkill no matter how pretty the user
interface is).

> * Simplify documentation writing for end users.
> 
> Actually, I think this is quite an important point. Writing a new tool
> probably means yet another XML (or some other format) to learn, which
> is Not A Good Thing (tm). IMHO it would be better to get away from XML
> completely and pursue simpler solutions.

+1.

> One such thing might be the OpenOffice plugin that generates Forrest
> files, which would help new projects a lot in writing/converting
> existing documentation.

I will assert OpenOffice is big and bloated and overkill too and not
simple at all. I like vi and subethaedit. And HTML.

> Another thing might be abandoning Forrest altogether for Incubation
> docs in favor of, for instance, a protected Wiki that only the project
> developers (and mentors, PMCs, ...) have write access to. And there's
> is probably a not-too-complicated technical way to convert this later
> on to Maven or Forrest format once the project comes out of
> incubation.

See Alex Karasulu's post to site-dev a while back for an approach where
we could have an admin-protected Confluence to serve as an editing interface
for xdoc.

There's a lot of ways to do things.

> Anyway, I hope you don't mind me making a case for using this as an
> opportunity to make Forrest better instead of abandoning it.

Well, basically I do. I've spent several years (ever since Avalon became
the first forrest user outside the xml.a.o group) working with forrest,
helping it to improve and try and help to turn it into something that
satisfies our simple use case, but its just not a good idea to keep going
down that path. I've read through about 9 months of discussion on the
site-dev list where basically the same discussion took place over and over
again which was very frustrating (or so it seems) for all the participants.
Nothing is ever going to get done if we keep having the same discussion
over and over again.

There is such a thing as "trying too hard" to get "full consensus" on a
topic that is "too vague". DavidC's site management proposal from so long ago
and each and every proposal after that has something along the line of
"Projects can use various documentation tools: Anakia, Forrest, Maven, raw
html, etc. Each system would have its own ways to report build problems to the
committer (e.g. xml validation, broken links, content and spelling errors,
configuration errors)." for a good reason. "There is more than one way to
do it" and this is going to be Yet Another Way.

I don't want to spend more time helping to improve Forrest or discussing the
relative merits of a variety of solutions. I have an itch to scratch and I
want to build a little piece of software to scratch it, in a way that is
compatible with all the goals and needs of the ASF, the Infrastructure Team,
the Incubator, the Gump project, and hopefully a few other projects. But I
don't want to concern myself with the needs of the Forrest community right
now as part of this effort, that's making it too hard to get anything done.


cheers,


LSD

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org