Rockbox.org home
Downloads
release
dev builds
extras
themes
Documentation
manual
wiki
device status
Support
forums
mailing lists
IRC
Development
bugs
patches
dev guide
Search



Donate

Rockbox mail archive

Subject: Re: Wiki added to Rockbox website
From: Björn Stenberg (bjorn_at_haxx.se)
Date: 2004-06-20

Christi Alice Scarborough wrote:
> I don't want to be difficult, but I see a few problems with that approach.

I don't see it as "being difficult", I see it as valuable feedback. Especially since you indicate you may be willing to help write the manual.

I was unclear in my previous mail. I completely agree that there will always be a great amount of manual work with getting polished PDF manuals together. I do not believe we will be able to auto-generate much, if anything, from the wiki pages.

What I do believe is that the wiki can speed up the process of writing the manuals. Today, simply understanding all the new features that has gone into the firmware since the last release/manual is quite a challenge that takes considerable time. Add to that the time to describe it clearly and exhaustively in a somewhat coherent language, and we quickly arrive at the point where we have to give up hope of releasing a manual simultaneously with the firmware.

If we programmers write a page in wiki (or modify an existing one) when we add or change a feature, I believe the research stage of writing the manual can be greatly reduced. Ideally, those programmer notes will be edited for better clarity and completeness, and finally used by the manual writers/editors to more quickly and efficiently put together a "frozen" PDF manual.

Thus, I see three "classes" of documentation writers:

- Programmers, who document what they have written
- Wiki editors, who pick up on the programmers' notes and expand it to more user-friendly help text
- Manual writers, who use the information in twiki when they write PDF manuals

I don't see the wiki as a panacea that will magically remove all the hard work of writing a manual. I see it as a way forward to improve the general level of Rockbox documentation, by allowing more people access to help. And I think that will benefit the manual team as well. 

-- 
Björn
_______________________________________________
http://cool.haxx.se/mailman/listinfo/rockbox

Page was last modified "Jan 10 2012" The Rockbox Crew
aaa