[mythtv-users] Myth Documentation, was: Please shut up!

Jon Larson jtlarson at u.washington.edu
Mon Jan 29 16:49:43 UTC 2007


Steven Adeff wrote:
> On 1/29/07, Brian Wood <beww at beww.org> wrote:
>   
>> On Jan 29, 2007, at 7:34 AM, Steven Adeff wrote:
>>     
>>> As for version'ing the wiki, and a note about this *should* exist on
>>> the home page, it is assumed on the wiki that unless the text says
>>> otherwise the information pertains to the currently released version.
>>> If upon the release of a new version the information becomes outdated
>>> it should be changed as soon as it is noticed, with the old
>>> information being dated to the previous release (so when 0.21 comes
>>> out, the information would say it pertains to 0.20).
>>>       
>> So one problem is that, as Myth advances, it takes a large effort
>> just to keep the WiKi up to date. What you are saying is that a lot
>> of entries need to be edited every time a new version comes out,
>> "treading water" just to stay afloat.
>>
>> And Myth is not the only moving target.  The kernel, IVTV, LIRC,
>> OpenGL, nVidia drivers and a lot more all keep "improving".
>>
>> So rather that "assuming" that an entry refers to the current
>> release, which virtually guarantees it will go stale without
>> continuing effort, what about some way to say "the following versions
>> were current at the time of this entry". That way a reader would know
>> immediately if the entry was current or not, without further work on
>> the part of the original creator.
>>     
>
> That should be part of the assumption, part of the front page note.
>
>   
As a Linux newb, I started out trying to do just that, and I can't count the number of times that it's gotten me into trouble, simply because I was following instructions that were out of date (but didn't have any indication of date or revision that they applied to) and I didn't have necessary knowledge to  see the errors ahead of time.

>> Yes the entry should be "noticed" and "updated", but this is the real
>> world and it can take a long time for that to happen.
>>
>> The only thing worse than no information is wrong information.
>>
>> Maybe we need a "documenter's list" as opposed to a "users" or
>> "developer's" list. I know that's pretty far-fetched but I'm just
>> throwing out ideas.
>>     
>
> No need.
>
> What we need is a note on the front page, something along the lines of
> "This is a wiki, not an official manual, as such, things tend to get
> dated. As new versions of MythTV and the required linux system and
> drivers advance information on these pages may become outdated. Unless
> otherwise noted, it should be assumed that the information on these
> pages pertains to the current version or has not been updated since it
> became outdated. If you encounter such a page please contact the user
> list."
>
> Then, hopefully, the list will become aware of pages which need updating.
>
>   
That sort of announcement does nothing to enable the beginner to make an 
intelligent decision  regarding the timeliness of the information they 
are viewing. Instead, it encourages  acting on unfounded 
assumptions--which is exactly opposite of a good user should do.

So here's my conclusion:

There are too many out-of-date wikis and instructions on the web for the 
instructions to be "assumed" trustworthy and up to date. So unless the 
information includes a tag or line that clearly indicates the 
revision/current date when the article was last checked, users will 
continue to post questions to mythtv-users simply because it is the 
easiest source of confirmed up-to-date information.

Jon

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mythtv.org/pipermail/mythtv-users/attachments/20070129/f3f6932a/attachment.htm 


More information about the mythtv-users mailing list