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?
