incubator-isis-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Alexander Krasnukhin <the.malk...@gmail.com>
Subject Re: Site & Documentation ideas
Date Fri, 08 Oct 2010 10:37:17 GMT
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 <dkhaywood@gmail.com> 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

Mime
View raw message