Okay, I hear the message about the wiki. :-) I'm going to first review
all the current documentation again and then I'll ping the mailing
list before I make any changes.
"Richard S. Hall" <[EMAIL PROTECTED]> writes:
> 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?
>>
>>
>
--
J Aaron Farr jadetower.com [US] +1 724-964-4515
馮傑仁 cubiclemuses.com [HK] +852 8123-7905
