Documentation Clean-up Week

[MarcGuay]

I noticed that there was some talk of organizing a Docs Clean-up Week at the DevCon and thought I'd take the lead on this one and see if I can't at least get some ideas organized.  So if you have any suggestions on where/how the documentation (either the wiki or the manual) can be improved in any way, you opinions would be greatly appreciated. 

I figured that there's no reason to create a new wiki page when we already have one basically set up at http://www.rockbox.org/twiki/bin/view/Main/ManualTodo.  I cleaned the plugins section but the rest could use some review. 

Some thoughts:

- Perhaps purging that page and starting from scratch would be easier than updating it.

- It might be wise to find a nice way to merge the WikiHome page with the Documentation Index so that there aren't two focal points to the wiki.

- Are there things in this wiki section that belong in the manual or vice versa? http://www.rockbox.org/twiki/bin/view/Main/DocsIndex#User_Interface

- Is there a plan for the flyspray feature requests?

- It needs to be decided if BatteryFAQ and LiIonFAQ are Archos-only or not.  If they are, make it clear, and if not, update them to be more universal.

- The flashing procedure for the Archos in the manual is a mess.  Tom Cole recently updated the wiki pages to be less confusing, so perhaps they could simply be copied to the manual and have the wiki pages deprecated.

[Llorean]

In regard to flyspray feature requests: What are you asking?

[MarcGuay]

I'm wondering if they're going to left as they are as a repository of ideas, or perhaps filtered-through and only keep those which have specific developer interest, or all be closed and only have new ideas opened as patches.  As it stands the Feature Request/Idea part of the project is in an unclear state.

[Llorean]

The intent is to reopen the feature request tracker in a manner where only developers can add features to it, so that it's not just a list of pie-in-the-sky ideas. Right now few developers are interested in even reading through it because there's so much noise on it.

Basically, we should probably close all existing feature requests. There hasn't been a final decision on whether we should close all of them, and reopen the ones individual developers find specific merit in, or close all the ones individual developers think there's no merit in. I personally think the first path will be most effective (since in the end, the second path will probably have the same result, just with more overall work).

[MarcGuay]

Any opinions on moving the Plugins wiki pages to the junkyard once they've all been added to the manual?  Is the MpegPlayer page an exception, or do we start a new VideoConversion page for the remaining dynamic information? 

I'm thinking that we may need to wait for the steering board to be created in order to decide on some "does this belong in the wiki or the manual?" and "what is the goal of the manual?" decisions.

[Llorean]

Actually, "what is the goal of the manual" would've been good for DevCon.

I think PluginIndex will always be necessary (just to have an easy reference as to what targets they're on) but I think the individual plugin pages should never be need.

Thus, yes, a VideoConversion page might be nice. I'd like, though, to settle on a single cross-platform method to recommend, rather than 400 different methods. Then we can actually try to provide limited support for that method (since we can actually be familiar with it). Then, the page can just document the specifics the output files must meet if made with other programs, and our one recommended method (which hopefully will eventually be RBUtil, though that may be a very long time coming).

[MarcGuay]

Just a quick thought on the manual vs. the wiki:  If we move all user documentation to the manual it may fall even further behind due to the fact that it's more complicated and requires commit access to update.  Even if users can submit bug reports to the tracker pointing out shortcomings in the manual, they could, as they've been known to, rot there for a while before being noticed, if at all, whereas the wiki tends to be more up-to-date and have better language editing because of it's populist nature.  C'est tout.

[Llorean]

The wiki also has a tendency to have very incorrect information (or at least misleading information, such as suggestions that the first step is to reformat a device, or whatever) because there is no review process for information to be included. So it kinda works both ways, at least the manual is "known good" information at the time of its writing.

Honestly, the documentation needs (in regard to stuff that belongs in the manual) shouldn't change that often anyway. And I think the intent is to put more pressure on those making commits that need documenting to actually get said documenting done. Most changes change things under the hood rather than in the UI anyway.