Rockbox Technical Forums
Rockbox General => Rockbox General Discussion => Topic started by: MarcGuay on February 11, 2008, 07:11:44 PM
-
As some of your may have noticed I've been sweeping through the wiki and trying to organize things a little bit. It's a pretty important source of information and I found a lot of it was either out of date or just messy enough to make it hard to find what you were looking for.
So, a few weeks ago I dumped the entire index (http://www.rockbox.org/twiki/bin/view/Main/WebTopicList) (minus the user pages, o' course) into a text file and started sorting them into categories. What I ended up with at the end, in the "active and useful pages" section, are now available on the documentation index page and the main wiki page (or immediate sub-pages of those, in the case of, say, specific player hardware & bootloader information).
The following pages are sitting in the I have been added to the glossary and can probably be deleted category:
* SoC (Simple terminology - Added to ProjectGlossary)
* NiMH (Simple terminology - Added to ProjectGlossary)
* LiIon (Simple terminology - Added to ProjectGlossary)
* FlashMemory (Simple terminology - Added to ProjectGlossary)
* MultiMediaCard (Simple terminology - Added to ProjectGlossary)
* FileFormatMI4 (Simple terminology - Added to ProjectGlossary)
... and some runner's up in the I have been merged with other pages and could most likely be done with category:
* IpodTips (merged with iPod FAQ)
* OtherTargets (merged with TargetStatus)
* MenuRework (dupe)
* IriverH100FAQ & IriverH10FAQ & IriverH300FAQ - All merged into iriverFAQ
* ManualHowTo (merged with GeneralFAQ)
And now the fun part. This is the somewhat unsorted, what am I? am I really old or do I just look that way? am I worth keeping in some kind of "historical" archive? do my feet smell? category:
* BootBox - these two pages are very confusing to me
* RomBox
* RockboxDevelopment (simply points to cgwyn and crosscompile - needs rewrite or deletion)
* FilesScreen ********for archos only, delete*********
* IpodExperimental
* GUIProposal *********dead******
* ManualFileBrowser *old manual stuff*
* WikiManual
* ManualFileMenu
* ManualMainMenu
* PlaylistScreen
* ManualRockboxInstall
* RecordScreen
* QuickMenu
* TrackScreen
* ManualWpsContextMenu
* NonArchos
* PluginScreen
* RealLife ?
* MissingAttachments
* RockboxGraphicalUIDesign (some guy trying to change the boot logo?)
* RadioScreen
* QuickStart
* PastedImagesForFourms (ancient thing, typo in name, hardly used)
* WikiRestore (historical)
* WebStatistics (neat if it was kept up to date)
* WPSTokenbasedHandling
* RockboxAudioAPIProposal
* RootMenu (discussion of main menu design - old)
* RuntimeDatabase (old discussion - pre Database)
* TagDatabase
* RockboxUserInterfaceProposal (archos)
* RockboxFlash (empty page)
* RockboxThemes (iRiver H100 - empty)
* RockboxUtilityOld
* RockboxUtilityQt (moved to RockboxUtility)
* VideoCodecs (ancient, r1)
* ThingsTodo (delete, points to->)
* SourceForge (dead)
* MediaCoder (link to a sourceforge project)
* HarddiskInfo (dead, replaced by HardDriveReplacement)
* ForumChanges (more old stuff, suggested forum changes?)
* FlashingRockbox (old)
* EncoderDiscussionMP3 (oldoldoldod)
* DocBoxObsolete (ancient)
* DesktopTools (installers - depricated by RockboxUtility)
* ChangeLog25 (old, changes between 2.4 and 2.5)
* BrokenSed (ancient)
* ThemeRepository (discussing new themes site, dead?)
* RockboxShots (kill - outdated)
* IpodInstallation (dead)
* IpodInstallationBeta
* IpodInstallationFromLinux
* IpodInstallationFromMacOSX
* IpodMacOSInstaller (old dead external program)
* IpodRestoration (iPod Unbrick? Delete?)
* IpodInstallationKr (depricated?)
* SansaE200Install (killed)
* SansaE200InstallBeta (killed)
* SansaE200RBootloaderPatching (outdated)
* KeymapOndio (depreciated)
* RockBox251 (Archos build, depricated)
* SanDisk (pointless?)
* IaudioBoot (out of date?) info moved to iAudio port page
* IaudioBootKr (out of date?)
* IriverFAQKr (dead)
* IriverInstall
* IriverInstallKr
* IriverPlaylistInstructions (not specific to iriver, should be in the manual? FAQ?)
* IriverRecording (not specific to iriver)
* IriverH10InstallationBeta (dead)
* IriverTeam (old)
* IriverTesting (dead)
* IriverRamLoad (obsolete)
* IriverNavigation (port navigation - killed)
* CodecTesting
* TriggerManual (delete after adding to the manual)
* NewForumProposal (way old)
* SortingPluginsProposal (old)
* CompiledSkinProposal (ancient but...)
* UseDisplayName (proposal, dead patch? archos only?)
* SettingsRecode (abandonned project?/discussion?)
* PowerConsumption (dead? iriver only?)
* FixingWaves (Rockbox ruins waves - out of date?)
* DocumentViewer (project - dead?)
* ColdfireEmulatorDevelopment (old, outdated?)
* BufferingAPIProposal (MoB depreciated?)
* MasLimitations (dead?)
* FmTunerProject (iriver only---delete***** done?) seems to still need work, ask around?
* SoapSealofApproval (old?)
* AllKeysConfigurable (dead proposal?)
* BookmarkUseCases
* BrowseByAlphabet (dead)
* ButtonActionIdea
* ButtonAssignments (depricated by manual)
* CustomMenus (very dead proposal)
* SubmitWPS (no longer applicable)
* MenuSettingsRecoding (done?)
* MetadataOnBuffer
* MetadataOnBufferTesting
* ViewDrawing (proposal for new theme interface, inactive)
* CuesheetSupport (committed)
* ReleaseAnnouncement30 (old)
* ShuffleExplained (old?)
* FlySprayLinks (no longer needed because of links on left panel?)
* SimpleGuideToCompilingKr (dead)
* MisticRiver (why? UserForums mention is good enough)
* OldPluginIndex (any point?)
* OpenOffice (DELETE)
* RockBox (ummm?)
and then the minor ToDo list:
* BlindFAQ (Archos only, should be updated)
* BlindFlashing (Archos only, should be updated)
* BatteryFAQ (Archos only, should be updated? or not worth it?)
* Clean up the Gigabeat port index, specifically, are the installation instructions still necessary?
---
So, I guess what I'm saying is that I've reached both the end of my energy for this task and my knowledge of Rockbox, and could use some energetic and knowledgeable help to bring it to completion. If anyone wants to go through the list of orphaned pages and decide whether they're worth keeping in the documentation index, deserve a proper but economical burial, or are worthy of a monument, that would be awesome. And if anyone wants to stare that ToDo list in the face, that would be nice too.
Otherwise, I'll continue to chip away at the wall as usual.
Marc
-
As a general rule, I don't think you should delete old stuff just because it's outdated. Suddenly it turns out to be useful, and you know know what or when.
-
Also, there might still be links pointing to those pages, in which case it would be nice to not have users led into dead-ends. I guess by "deleting" I mean "clear & redirect"; the wiki will keep the history if anyone's interested and needs to track it down.
But in the meantime a lot of these pages are just cluttering things up and leading to a lot of avoidable support questions. You can't blame the users for not understanding things if your documentation still contains an older, outdated copy of "the manual" which they're constantly being told to refer to.
-
I've long found that the wiki is too disorganised to find useful information quickly. I realise that the history can be useful in some cases, but in many cases the out of date "information" might as well be called misinformation. I applaud Marc's work.
Might it be practical to start a new wiki, with a clear, documented structure, then move good pages over into it. The old wiki could be left alone (complete with out-of-date stuff), but relegated to a secondary URL - wikiarchive or similar.
pondlife
-
I've long found that the wiki is too disorganised to find useful information quickly. I realise that the history can be useful in some cases, but in many cases the out of date "information" might as well be called misinformation. I applaud Marc's work.
Absolutely
Might it be practical to start a new wiki, with a clear, documented structure, then move good pages over into it. The old wiki could be left alone (complete with out-of-date stuff), but relegated to a secondary URL - wikiarchive or similar.
Would it be sufficient just to have an 'archive' category that all such pages could be classified as, which would keep them within the main body of the Wiki, but allow them to be filtered out in the search engine?
...If anyone wants to go through the list of orphaned pages and decide whether they're worth keeping in the documentation index, deserve a proper but economical burial, or are worthy of a monument, that would be awesome...
Is this the time (and it may well not be) to update the manual with the useful snippets of info in the Wiki and then delete the pages. I know when I first started using Rockbox that I found some little bits of info in the Wiki that were not in the manual about how specific things worked, or config options that are not well known.
-
Is this the time (and it may well not be) to update the manual with the useful snippets of info in the Wiki and then delete the pages. I know when I first started using Rockbox that I found some little bits of info in the Wiki that were not in the manual about how specific things worked, or config options that are not well known.
I did a bit of this while filtering through the pages and added a few ToDos to the tracker as a result. The main GeneralFAQ also soaked up quite a bit of information that was scattered about.
As for the out-of-date pages, I guess we have a few desirables:
1) Keep them for future reference and usability (I resurrected the MenuLayoutDiscussion page recently, and was happy not to have had to create a new page for it), yet...
2) Make sure that they aren't perceived as up-to-date information, either by excluding them from searches or by simply adding a very bold and very colourful header indicating their status.
I suppose the simplest solution would be to have a "Museum" section at the end of the documentation index which includes all of the aforementionned pages with notices added to them.
The first step, though, is for someone with the knowledge required, to go through the long list I posted and decide which of those pages should be part of the main documentation index and which should be put in the out-of-date section, because this is something I can't do.
---
Edit:
Okay, I've done all that I can. The Rockbox Museum is open for business. There are no longer any orphaned pages floating around in the wiki (unless I missed some, which I'm sure is possible).
-
I thought I'd cash in on some of this "let's clarify the documentation" momentum and ask that someone with the knowledge sync up these two wiki pages:
http://www.rockbox.org/twiki/bin/view/Main/FlashingRockbox
and
http://www.rockbox.org/twiki/bin/view/Main/BootBox
-
I just want to applaud your work as well. Good stuff!
FWIW: I try to revisit the pages I started every few months and try to "clean them up".
Thanks!
-
I thought I'd cash in on some of this "let's clarify the documentation" momentum and ask that someone with the knowledge sync up these two wiki pages:
http://www.rockbox.org/twiki/bin/view/Main/FlashingRockbox
and
http://www.rockbox.org/twiki/bin/view/Main/BootBox
Belatedly, I've updated these Wiki pages with my understanding of how the Archos machines can be flashed with Rockbox. If this is satisfactory, maybe details from the BootBox page can be included in the Archos manuals.
-
I recently went through most of the plugin pages that had next to zero content (!Documentation! flags). This coming week I hope to work on the Battery FAQ and update it for batteries in general (not just the Archos, but not really any specific device either).
EDIT: I should note that I have NOT removed the !Documentation! flags on any Wiki pages (because I don't know whether they need anything more or not). Also, in the Wiki, I am known as MichaelCarr.
-
It's great to see other people getting keen on maintaining the documentation. Keep it up! There was a mention of a "documentation-binge week" at the DevCon which I'd love to see followed through on.
On another note, I had a few ideas recently that I'd like some feedback on before going ahead with. They're tiny little shifts but noticible enough that other opinions would be nice:
1) Move the Rockbox Museum stuff to it's own page, it's really just a pile of crap which might come in handy someday and therefore doesn't need to be easily accessed frequently through the DocsIndex.
and
2) Shift the HardwareProjects page to the DocsIndex so that those pages are more easily accessible, particularly the HardDriveReplacement page which seems rather popular.
Rocque on.
P.S. Strife89: I've had a note on my desktop that says "FIX BLINDFAQ" for months now because it suffers from the same out-of-dateness as the Battery FAQ... If you've got some extra time? :)
-
Hopefully I can do it in bits and pieces throughout this week. :)
EDIT: If you don't mind, can you leave some suggestions? ;)
-
It's great to see other people getting keen on maintaining the documentation. Keep it up! There was a mention of a "documentation-binge week" at the DevCon which I'd love to see followed through on.
I would also like to see/participate in this.
1) Move the Rockbox Museum stuff to it's own page, it's really just a pile of crap which might come in handy someday and therefore doesn't need to be easily accessed frequently through the DocsIndex.
A good idea. This (and the DocsIndex itself) could be done, almost automatically, using Wiki categories. I don't know if you looked into these when doing the clean-up, but if we re-categorised all the Wiki pages into more discrete groups, then the index pages just about write themselves.
For instance, the WebHome (http://www.rockbox.org/twiki/bin/view) page mostly consists of these few searches to generate content:
Some pages of interest:
---++ Documentation
* [[http://www.rockbox.org/manual.shtml][The Rockbox Manual]] - Get your copy here
%SEARCH{"^CategoryFrontpage:.*\[.*Documentation.*]" scope="text" regex="on" nototal="on" nosearch="on" format=" * [[$topic]] - $pattern(.*?CategoryFrontpage:([^\[]*).*)" }%
---++ Functional Ports
%SEARCH{"^CategoryFrontpage:.*\[Ports]" scope="text" regex="on" nototal="on" nosearch="on" format=" * [[$topic]] - $pattern(.*?CategoryFrontpage:([^\[]*).*)" }%
---++ New Ports
%SEARCH{"^CategoryFrontpage:.*\[New Ports]" scope="text" regex="on" nototal="on" nosearch="on" format=" * [[$topic]] - $pattern(.*?CategoryFrontpage:([^\[]*).*)" }%
---++ Miscellaneous
%SEARCH{"^CategoryFrontpage:.*\[.*Misc.*]" scope="text" regex="on" nototal="on" nosearch="on" format=" * [[$topic]] - $pattern(.*?CategoryFrontpage:([^\[]*).*)" }%
---
%INCLUDE{"RecentChanges"}%
I still haven't figured out, though, what benefit the Parent/Child relationship between pages really has...
-
Strife: Sorry, no real suggestions. If I had a clue where to start I would have done it myself. :)
bascule: Yeah I looked at the categorization options but ended up just going with hard-coding because it would have taken even longer to do and the wiki isn't really complex enough to warrant it, in my opinion.
-
It would be nice if the wiki front page included a prominent (perhaps toward-top, centred, larger-fonted) 'Search the Wiki' option box/field. A lot of information on the wiki is referenced in the forums and it can be wiki-tricky (sorry) to unearth it. Maybe it's a 'dumbing down' kinda suggestion but I can't see it interfering with the functionality of the site and it might make it easier for semi-casual users, like me ;) to find additional information which might ultimately reduce the forum headaches for you guys? (Personally I'd reconfigure the box at top right to simply use wikiwords only, for those who know them.) If this has been covered already or i'm missing something really obvious i'm sorry!)
-
I agree that a Search box next to the Go box would be useful. Another option, which I use frequently, is to simply go to the DocsIndex and CTRL-F(ind) keywords - they usually turn up what I'm looking for.
-
Yeah that has pretty much everything that's useful on it. But I was thinking of people who are more or less clueless about Rockbox, Twikis or websites even. I can find my way around the Rockbox site relatively well, but it's not the most intuitive I've used. So I guess I'm talking about that old chestnut of functionality versus friendliness. One should not preclude the other. Anyway I appreciate the wiki and your efforts to 'clean-it-up'!