Hi Gert,
concerning the homepage, I'm agree to simplify this page. The
OpenOffice.org homepage is clean and easy to use. I think that we need
to distinguish two kinds of people on ServiceMix:
- the users who looking for the documentation (SMX manual), the
distribution and support( help/bugs tracking)
- the power users/developers who looking for a deeper documentation
(architecture manual), some contribution guide, etc
So displaying link to this topics directly is clean on the homepage
(like OpenOffice.org does).
Concerning the documentation, from my point of view, the wiki should be
reserved for documentation not in the manual.
The manual targets are user. So the wiki can contain advanced
documentation (architecture, advanced topic) and could be referenced by
the manual.
I think that the manual should be considered as a project itself, with
sources (DocBook files), versionning, etc.
Concerning the "easy" edit, I need to test if confluence is not able to
provide a DocBook file from a wiki page (it can imports from DocBook, so
maybe it can extract :)). In this case, the DocBook source can be hosted
on the wiki, gathered by the maven plugin to generate the target outputs
. This cinematic is used for the Camel manual using Prince.
Regards
JB
Gert Vanthienen wrote:
L.S.,
Yeah, I also think our current home pages are a bit 'crowded' with too
many links and just confusing new users on where they should go to get
started. Personally, I would love to see a home page like the ones
http://www.openoffice.org or http://rubyonrails.org are having, with a
few very obvious links to get people going. If we could have that
low-barrier landing page together with the improved, in depth
documentation we're going for with the docbook/wiki combo, that would
be a real asset to this project.
For the docbook/wiki dilemma, that's a hard one. Obviously, using
something like docbook to generate the documentation web pages, pdf
documents, ... would offer some advantages: it would probably be
easier to integrate pages from all kinds of places (felix karaf,
camel, components, nmr, ...) to get everything a user needs nicely in
one place. Another benefit would be the fact that the documentation
itself is versionable too, so we no longer have documentation for all
versions together. However, I also really like the easy-to-edit
documentation we now have with the wiki. Not sure what the ideal
solution would be here, something where we edit pages in the wiki and
then extract/aggregate them with docbook and have some options to add
generated docs for the components and their xml schema's?
Regards,
Gert Vanthienen
------------------------
Open Source SOA: http://fusesource.com
Blog: http://gertvanthienen.blogspot.com/
2009/11/19 Chris Custine <[email protected]>:
I really like the proposed Home Page as well. I agree with Jamie that we
should flatten out ServiceMix 3 and 4 in the navigation column a bit. To
take his suggestions even further, I propose that we have ServiceMix 3 and
ServiceMix 4 as their own top level menu items, with sub-items for
documentation, downloads, source, etc. For ServiceMix 4, I am thinking the
Features, NMR and Kernel variations should be de-emphasized slightly by just
referring to Features as ServiceMix 4. This is what most people think of as
ServiceMix 4 anyway. We could differentiate between them on the ServiceMix
4 main page once the user gets there.
I think the main page has been confusing for a while so I think this is a
great time to dig in and revise it a bit before we release the 3.x updates,
4.1, and the new components releases. I think flattening things out to be a
bit more concise on the main page will help a lot of people navigate the
sire and understand the differences between SMX3 and 4.
I'll be happy to spend a couple of days reviewing and making these updates
if everyone generally agrees on this.
--
Chris Custine
FUSESource :: http://fusesource.com
My Blog :: http://blog.organicelement.com
Apache ServiceMix :: http://servicemix.apache.org
Apache Directory Server :: http://directory.apache.org
On Thu, Nov 19, 2009 at 7:02 AM, Jamie G. <[email protected]> wrote:
I really like the new home page design :)
The only part that I could see a small improvement is in the
'Community' side panel. Specifically the three entries; Servicemix
4.0, Servicemix Kernel, and Servicemix NMR. Could we reorganize these
into:
Servicemix 3 (linked to http://servicemix.apache.org/getting-started.html)
Servicemix 4 Features (linked to
http://servicemix.apache.org/SMX4/index.html)
Servicemix 4 NMR (linked tohttp://servicemix.apache.org/SMX4NMR/index.html)
Servicemix 4 Kernel (linked to
http://felix.apache.org/site/apache-felix-karaf.html)
Servicemix Components (linked to
http://servicemix.apache.org/components-list.html)
This would help let new users quickly identify the different projects
under Servicemix and to which version(s) they belong.
Cheers,
J
On Thu, Nov 19, 2009 at 5:23 AM, Jean-Baptiste Onofré <[email protected]>
wrote:
Yes why not. It can be a step two in the documentation project.
From my point of view, the purpose of wiki -> DocBook is to avoid to
rewrite
all the content.
After we have two ways:
1/ the wiki is the master and the documentation is generated from there:
the
advantage is that it's simple to edit and provide but I'm not sure that
the
generated documentation will be very fine
2/ the wiki pages will be deprecated and the sources are "static".
Regards
JB
Charles Moulliard wrote:
That's perfect for me.
Probably that we will need also a command to transform docbook into
HTML page of wiki in order to synchronise docBook with Wiki in a
symetric way.
I don't know if this is interesting but there is a confluence docbook
converter plugin :
http://confluence.atlassian.com/display/CONFEXT/Confdoc+DocBook+Converter
Regards,
Charles Moulliard
Senior Enterprise Architect
Apache Camel Committer
*****************************
blog : http://cmoulliard.blogspot.com
twitter : http://twitter.com/cmoulliard
Linkedlin : http://www.linkedin.com/in/charlesmoulliard
Apache Camel Group :
http://www.linkedin.com/groups?home=&gid=2447439&trk=anet_ug_hm
On Thu, Nov 19, 2009 at 9:37 AM, Jean-Baptiste Onofré <[email protected]>
wrote:
Hi all,
FYI, I have begun to write a maven plugin (in my sandbox repo) to:
- transform a DocBook documentations into HTML, FO, PDF
- be able to get confluence wiki HTML source, apply JTidy on it to
transform
into XHTML and apply a XSL to go to DocBook.
This plugin will be used to generate the ServiceMix manual from
provided
DocBook document and to init these documents from the wiki.
I would like to resume the work on the manual and, in the same of the
first
manual release, promotes http://servicemix.apache.org/home2.html to
give
more visibility.
What do you think about this ?
Thanks
Regards
JB
--
Jean-Baptiste Onofré (Nanthrax)
BuildProcess/AutoDeploy Project Leader
http://buildprocess.sourceforge.net
[email protected]
PGP : 17D4F086
