[mythtv-users] Wiki reorganization (was re: MythArchive Guide - Burning TV Programs to DVD)

[Steven Ellis]

Nick Morrott wrote:
> On 14/03/07, Rod Smith <mythtv at rodsbooks.com> wrote:
>   
>> On Tuesday 13 March 2007 20:20, Steven Adeff wrote:
>>     
>>> On 3/13/07, Rod Smith <mythtv at rodsbooks.com> wrote:
>>>       
>>>> Sorry to hijack this thread, but this comment does bring up an important
>>>> point: The wiki really is confusingly organized. There's lots of overlap
>>>> between different high-level categories and between individual entries,
>>>> making it hard to find things sometimes. This is understandable given the
>>>> organic way in which a wiki grows, but IMHO, it may be time to "trim the
>>>> tree," as it were, and do some high-level editorial maintenance on the
>>>> wiki.
>>>>         
>>> I agree, both that some sort of organizing needs to take place and
>>> that it would be a relatively big undertaking.
>>> What do you propose?  perhaps working it out before going through with
>>> it will help minimize the pain and confusion.
>>>       
>> I think that a three-step process might work:
>>
>> 1) Evaluate what's there now. Perhaps there's a tool that could spider
>>    through the wiki, showing its overall organization. This would help
>>    the editors understand what's there. Whether or not there's a tool
>>    to help summarize the structure, the editors will have to read, or
>>    at least skim, most of the existing material.
>>
>> 2) Plan a new structure. Using knowledge gained from step #1, a new
>>    structure could be planned. An outline might work, or perhaps
>>    a flowchart. Editorial rules and guidelines could also be developed,
>>    both for the reorganization and (perhaps) for future entries to
>>    help maintain the structure.
>>
>> 3) Implement the changes. This is the part that would take the most
>>    work, I expect.
>>
>> IMHO, the bulk of step #2 would be best done by one person, although of course
>> feedback from others would be desirable. Step #3 would almost certainly
>> require several peoples' contributions if this were to be done in any
>> reasonable period of time. Ideally, the wiki could be locked down for a
>> couple of days while the editors make their changes; however, if there aren't
>> enough editors this might be impractical and a plan to implement the changes
>> in stages might need to be developed.
>>
>> FWIW, I've written quite a few books on Linux, so I've got a good idea of how
>> to organize technical documents, and I'm willing to take the lead on step #2.
>> OTOH, a wiki's hyperlinks offers opportunities for more complex structures
>> than a printed book can support, so somebody with more wiki or Web page
>> design experience than I've got might be a good choice to take the lead on
>> step #2.
>>     
>
> Even though I'm not a Gentoo user, I seem to find information
> logically organised on their wiki (http://gentoo-wiki.com/Main_Page).
>
> A gripe with the MythTV wiki HOWTO section, which is alphabetised, is
> that pages may not appear under the most obvious section (section is
> dictated by page title) and you may just have to check all articles to
> find the one you want. You can clearly search the wiki (which I tend
> to do) but a properly maintained index would aid users no end.
>
> Another personal bugbear of mine is the disparate nature of Linux
> documentation in general :) I want it all in one place, organised and
> complete. Documenters all want to write their own page detailing a
> process or providing tips and tricks. Google is realistically still
> the only answer.
>
> Note that I applaud anyone that goes to the effort of documentation -
> it's the organisation of the data which causes the headaches :)
It is also a problem setting the level for the documentation. How do you
pitch it

1. Consumer
2. Power User
3. Developer

I've been trying with the myPVR guides to cover 1 and hint at 2.

For example our simple guide on using the EPG navigation keys at
http://openmedia.co.nz/openmedia/content/view/72/59/. Is this pitched at
the right level?

I'm also trying to keep most of our docs generic enough to be applicable
to all MythTV users, but again not everyone has everything installed the
same way. As already mentioned in this thread not everyone might have
MythArchive installed.

Steve

-- 
Steven Ellis - Technical Director
OpenMedia Limited
email   - steven at openmedia.co.nz
sales   - sales at openmedia.co.nz
support - support at openmedia.co.nz
website - http://www.openmedia.co.nz