I think it's right choice to use Maven to generate docs. It won't take too long to keep them up to date. From my point of view http://commons.apache.org is perfect. It has only information you need. Compact & clear. Every java developer is familiar with this organization.
Well, one idea about appearance thats easy to fix. At http://www.nakedobjects.org/ the left panels background has the same color as central panel. You don't get visual border for panel & center. It's not good. Compare with http://commons.apache.org. You have clear distinction between panel & center. Its easer to read & navigate. On Fri, Oct 8, 2010 at 12:08 PM, Dan Haywood <[email protected]> wrote: > 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, at > https://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. > > > -- Regards, Alexander
