One other approach that geronimo has taken is to have their main site
done by forest or the like, and have a space for their user's guide. See:
http://geronimo.apache.org/documentation.html
1.1 docs:
http://cwiki.apache.org/GMOxDOC11/apache-geronimo-v11-users-guide.html
1.0 docs:
http://cwiki.apache.org/GMOxDOC10/apache-geronimo-v10-users-guide.html
Not saying that they're a model citizen of how to document a project,
but something to consider.
- Dan
Dan Diephouse wrote:
I think you can expand the definition of HTML in Hani's message to
include things like DocBook and the like. I agree with the concerns
about the wiki, but I also share the concerns about making it hard to
write documentation. As a developer, I often write user facing docs,
not just developer facing docs, so I feel this directly affects me.
I guess at this point I don't really like any of the options. What
would be perfect is if Confluence was SVN based and allowed you to
lock down the active version of the page.
What are people proposing we use for our basic website? And for the
user's guide?
- Dan
Johnson, Eric wrote:
Hani,
The developers wouldn't necessarily have to write HTML documentation.
They could still use the Wiki to write developer facing docs and the
like. We could just link to these from a central web site or use the
export function out of Confluence for this purpose.
My hope is that there will be a separate set of user facing docs that
will be more tightly reviewed for both technical accuracy and
consistency before being published.
Cheers,
Eric
-----Original Message-----
From: Hani Suleiman [mailto:[EMAIL PROTECTED]
Sent: Wednesday, August 30, 2006 1:53 PM
To: [email protected]
Subject: Re: Wiki and Web
I'm torn, I agree that:
1) Confluence looks like crap
2) A wiki is a horrible way of ensuring a consistent and coherent set
of documentation (case in point, xfire docs)
However:
1) It is possible to customise the export templates to look less
retarded and more professional
2) Convincing developers to write html documentation is tricky, if
not impossible, unless you throw money at them.
On Aug 30, 2006, at 1:49 PM, Johnson, Eric wrote:
Dan,
I've been thinking about the web site thing a bit more and still
don't
think Confluence is the way to go for the front page. Here are a
few of
my concerns:
* While Confluence does make editing the content easy it is also
pretty
limited in its layout capabilities.
* If our Wiki and our web site look the same, what is the point of
having both?
* Since the Confluence instance we are using is not specific to our
project, how much control over look and feel do we have over the
resulting output?
* Can Confluence make use of CSS and Javascript?
Mostly, I'm concerned that using Confluence does not provide a good
base
for creating a really professional looking web presence.
The approach I'd prefer is to use straight HTML to build the main
page
and perhaps some of the other pages. From that base we can add
links to
the Confluence instance and other content.
I understand that this means checking the HTML back into SVN, but
that
really is not that big an issue in my opinion. It provides a good
way
for the whole community an opportunity to see what is being added
to the
page before it gets pushed out to the Apache web server.
Cheers,
Eric
-----Original Message-----
From: Dan Diephouse [mailto:[EMAIL PROTECTED]
Sent: Thursday, August 24, 2006 4:40 PM
To: [email protected]
Subject: Re: Wiki and Web
Johnson, Eric wrote:
Dan,
I agree that most of the Celtix stuff is probably irrelevant to
CeltiXfire, but figured we needed to start somewhere...
I can certainly put something simple together that has a project
description and associated information. It will probably be easier
for
me, initially at least, to put this together using straight HTML.
I'm
sure confluence is easy to use, but I've never actually done it.
Its very simple, just go to a page and click Edit :-)
For site generation I'm not sure Forrest is actually the best way
to
go
either. I just put the Celtix info together as an experiment. I'm
not
sure I like using the Confluence to build the main site either
though.
Is there a way to lock down who can edit the content?
Yes, only people who we give permission to can edit it.
Does this mean that the wiki and the Web site are the same?
In essence yes. But the wiki gets exported to SVN. Here is an
example:
The published site: http://incubator.apache.org/activemq/
Confluence: http://goopen.org/confluence/display/ACTIVEMQ/Home
I suppose what I'm getting at is that I like the idea of having a
wiki
that people can edit as a tech/dev zone sort of thing, but not as
the
entry to the project. I like the idea of a static site that is
reviewed
before being published as the front of the Web site. I think the
front
page of the Web site should be a static HTML page that is stored
separately from the wiki. From that page we can link into
Confluence,
Maven derived stuff, or Docbook derived stuff. That way the front
page
is more tightly locked down and can present the best face for the
project.
We have a lot of control over who we allow to do edit things, so I
guess
I don't think it will be that big of an issue. I think the
benefits of
not having the edit/generate/publish cycle outweigh the reviewing.
Are people going to go defacing the front page? I don't really
think
so.
Its the same principle as the wikipedia. The ease of edit outweighs
the
dangers of someone doing something on a page. All of us have SVN
logs/RSS feeds for the wiki. I watch the changes to the XFire wiki
quite
religously, and will continue to do so for CXF.
It can be just straight HTML and thus avoid the generate->publish
step.
You still need to commit them to svn. With Confluence we can hook
it
up
so its just an Edit -> Save.
As for the docs, I think we need to have them in a format that
allows
other projects to easily consume them and work with them as they
want.
Keeping them in Docbook allows others to take the docs and build
them
into their own doc set if they like.
Yes and no. I assume you're talking about how IONA may want to
embed
the
documentation in its products? Wouldn't this only really be a major
issue on things like the users manual? This was why I was
mentioning
that we might want to have a hybrid approach.
Cheers,
Eric
-----Original Message-----
From: Dan Diephouse [mailto:[EMAIL PROTECTED]
Sent: Thursday, August 24, 2006 2:58 PM
To: [email protected]
Subject: Re: Wiki and Web
Hi Eric,
I'm not sure that all the old Celtix content will be all that
relevant.
Probably the tooling stuff will, but I'm looking through the rest
of
the
celtix website and it doesn't seem like much of it should come
wholesale
to Apache.
How about we get a simple website with the mailing list, source
repository, and project description up. I think it would be
easiest
to
just use confluence for this stage and have the html sync/export
dumped
to the svn repository for our website. If people are really keen
on
using forest, thats fine, but I find Confluence+Export removes
the
extra
generation + publish steps.
Concurrently, lets figure out what our requirements are for
documentation. I'm not a huge fan of the write, generate, publish
approach. I find the the wiki approach much faster as you get an
instant
look at what your docs look like and there is no delay in
publishing.
I
understand we may want to have stuff checked over before being
instantly
published though, so maybe we can do a hybrid approach with the
manual
as a forest/xdoc/docbook type of thing and the rest of the site
backed
by a wiki.
Regards,
- Dan
Johnson, Eric wrote:
I have a Forrest based site ready that contains most of the
content
ported from the old Celtix site. It could easily be deployed and
updated
to include any Xfire content.
-----Original Message-----
From: Dan Diephouse [mailto:[EMAIL PROTECTED]
Sent: Friday, August 18, 2006 3:24 PM
To: [email protected]
Subject: Re: Wiki and Web
Jason van Zyl wrote:
On 18 Aug 06, at 1:11 PM 18 Aug 06, Johnson, Eric wrote:
Have we decided on a Wiki to use?
I setup Confluence:
http://cwiki.apache.org/confluence/display/CXF
We can use it or something else but that's there for perusal.
I'm deifnitely for using Confluence. It kicks the pants off
Moin
Moin.
What are we going to do about getting a web presence for
the project?
We can either create a Maven site, use the autoexport plugin
for
Confluence to turn wiki pages into a static site, or use
something else.
Maybe a good first step would be to hook in the autoexport
plugin for Confluence while we investigate our needs for
documentation? This would allow us to get a site up quickly.
- Dan
--
Dan Diephouse
Envoi Solutions
http://envoisolutions.com
http://netzooid.com/blog
--
Dan Diephouse
Envoi Solutions
http://envoisolutions.com
http://netzooid.com/blog
--
Dan Diephouse
Envoi Solutions
http://envoisolutions.com
http://netzooid.com/blog
--
Dan Diephouse
Envoi Solutions
http://envoisolutions.com
http://netzooid.com/blog
