Picking up on Dave's points, then, the Cocoon site is nice to look at,
and what's encouraging is that it is a Maven generated site. Struts is
also Maven-generated, though not styled particularly. Wicket looks
nice, but isn't Maven (I'm pretty sure).
We probably should distinguish aesthetics from organization. The fact
that both Cocoon and Struts are Maven-generated and are easily navigable
means that there's nothing wrong with our decision to use Maven as a
technology for writing site docs. The thing that is important though is
that we get the organization right.
I think that Rob and I have a pretty good idea of what we want the site
to look like; screencasts will only further improve the site. My view
is we execute towards that vision first, then see what we want to change.
In the meantime, though, let's keep the conversation open and capture
any good ideas on the wiki. I've captured Dave's points on the Isis
wiki, at
https://cwiki.apache.org/confluence/display/ISIS/SiteAndDocumentationIdeas.
Thx
Dan
On 08/10/2010 10:10, Dan Haywood wrote:
A few of the committers have been having a conversation off-list about
the site documentation. I'm just copying some of those points here so
that they are public, and for others to come in if they have ideas or
thoughts.
*/Original point that was made:/
*
It's damn hard to find actual documentation from
http://www.nakedobjects.org/index.html. It isn't trivial to click
Component -> Application Library just to find some concrete docs. I
think that the site map should be reviewed.
/*Dan's thoughts:
*/
All this stuff is work-in-progress... Rob and I are aware that this
stuff needs to be very easily accessible.
If you have any firm ideas, that'd be great; pop them onto the Isis wiki. I've
copied up some correspondence on isis-dev between me and
Dave there, athttps://cwiki.apache.org/confluence/display/ISIS/ScreencastIdeas.
/*Rob's thoughts:*/
This stuff is so important. Dan and I have been talking about it for a
while now and its one of the main thing that we need to concentrate on
for the move to Apache. If you do something, or try to figure something
out, then make a note of it so we can add it to the documentation. Dan
and I will structure and make the documentation build and then we need
to make it easily accessible.
I know I'm just repeating what Dan has said, but I want you to know that
we recognise that and are committing ourselves to working on it.
/*Dave's thoughts:*/
Hey Everyone,
I was looking at some of the other Apache projects and I thought the Apache
Cocoon
site had a pretty good layout that made it easy to get started and worked it's
way up
to contributing to the project. On the Cocoon site, I find it easy for both
the beginner
and the advanced developer to find the information they need within a few clicks
and the documentation and reference material are easy to find.
Two other sites that I found to be organized well are the Apache Struts and
Apache Wicket site.
I think we can take advantage of some of the styles of these sites and make it
easy
for all levels of developers to use the site effectively and efficiently.
