Hi,
I've been thinking about the wiki / offline documentation
scenarios for a while as well.
Another great thing about the wiki is that
edits are immediately visible for everyone.
Personally though I have a need to automate
things like look and feel, table of contents,
etc. so I created a mojo for writing an eclipse
documentation plugin.
The pages generated could be pulled directly into
a site and be launched in the eclipse info center
at the same time.
Also, the content first goes into an xml
document that the mojo reads and generates the Eclipse
documentation plugin.
Deployment functionality could be added to
deploy directly to svn and subversion could
then have a hook regenerate the documentation website.
I'll be glad to share more details on the implementation
of this stuff if anyone is interested.
If you want to see an example of what it generates
you can find it here:
https://svn.apache.org/repos/asf/directory/sandbox/oersoy/guides/org.apache.directory.contributor.guide
https://svn.apache.org/repos/asf/directory/sandbox/oersoy/guides/rpm.factory.user.guide
The code for the plugin that generates the checklist guide is here:
https://svn.apache.org/repos/asf/directory/sandbox/oersoy/documentation.checklist.parent
There is another mojo that generates the RPM Factory guide that I
need to upload. It is also used to create the LDAP DAS Design Guide
in my sandbox.
Cheers,
- Ole
Richard S. Hall wrote:
Ultimately, I agree with everything you had to say about the web site,
except for the recommendation not to use a wiki. I don't have a love
affair with wikis and I agree that often they do not look good, but the
number one reason why I want to use a wiki is that I hate to do
documentation, but wikis make it reasonably easy for me to create
documentation or to make quick edits when I become aware of a mistake.
Thus, I find that I maintain wiki documentation more since it has a
lower barrier. I think this is important.
For example, on another thread today someone mentioned something about
the 'Launching and Embedding Felix' document, so I quickly jumped over
to the wiki page and tried to add a few sentence to the page to make a
specific issue more clear. It is nice to have this ease of
editing/deployment.
We just have to strive to have our statically generated pages not look
ugly...they perhaps need some work in this area now... :-)
-> richard
J Aaron Farr wrote:
"Richard S. Hall" <[EMAIL PROTECTED]> writes:
Matthias Luebken wrote:
I suggest that you update the website felix.apache.org so that the
ongoing improvements are reflected on the website. If you don't look
into the Jira Issue Tracker, you don't have the impression that there
is much progress at Felix.
Agreed.
I've mentioned more than once that I'd like to help on this front.
The website is real weakness for Felix, IMHO. Here are my thoughts on
a good website:
- Very organized, quickly addresses the audience and helps them find
the rights spot (ie- who are you? a developer of felix? a user of
a plugin? a user of some other software that happens to use felix?
interested in OSGI?...)
- VERSIONED documentation. That is, the documents for Felix 0.8, 0.9
and 1.0 are all available and not erased. This includes javadocs.
- Available with the downloads and if possible, in a printer friendly
format.
- Include more "how to use the software" documents than "how it works
internally" documents. This means at least one decent tutorial.
Screencasts are even better.
All of this is difficult, though possible, with a wiki. I think
wiki's are great for community created documentation but they must be
well maintained, including pruning and re-organization. A website
should have a flow to it, and wiki's often don't.
My personal preference is to author the documentation in some XML
format and reserve the wiki for FAQ entries, quick whiteboarding of
ideas, and soliciting community documentation. Good articles from the
wiki can then be pulled into the main, static site.
That's my thoughts. I'd like to contribute to Felix and the best way
I could do that right now is with the website, but I'd like some
feedback from the community before I either start hacking through the
wiki or writing up huge amounts of docbook or xdoc.
Thoughts?
