Hello Aaron,
On May 21, 2007, at 7:38 , 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.
I've mentioned more than once that I'd like to help on this front.
Like we discussed at ApacheCon, I'm glad you're willing to help!
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?...)
Agreed, we need a good discussion about the structure of the site.
Restructuring the site based on the different audiences you describe
makes sense.
- VERSIONED documentation. That is, the documents for Felix 0.8, 0.9
and 1.0 are all available and not erased. This includes javadocs.
We already have this:
Confluence is versioned, there is a full history of every page
available. We might want to include (part of) the site in our
official releases (starting at 1.0 probably). Since the auto exporter
generates a static copy of Confluence, we can do that as part of the
release process. Alternatively, we can do something like create a
document root for each version as for example the Cayenne project does.
Generated artifacts such as JavaDoc and unit test and coverage
results should be generated by a continuous build or done as part of
creating the release (and we can always regenerate them anyway from
the repository).
- Available with the downloads and if possible, in a printer friendly
format.
HTML should be pretty printer-friendly. We might need to adapt the
CSS to include more printer specific hints.
- 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.
Feel free to help us out here! There are already quite a few OSGi
tutorials available, but having one specifically for Felix might make
sense (and at least we should try linking to all available and
relevant information).
All of this is difficult, though possible, with a wiki. [...]
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.
This is where I don't agree. I think that Confluence works just fine
for creating our site and makes it far easier to contribute than
having a set of XML files in a repository. There are ways to
structure and restructure our information and I think keeping
everything up to date is actually easier in Confluence than it would
be in a set of XML files.
Greetings, Marcel
