[mythtv-users] Help with documentation

[Philip Brady]

> Date: Mon, 22 Jun 2015 09:56:53 -0400
> From: cats22 at comcast.net
> To: mythtv-users at mythtv.org; mythtv-dev at mythtv.org
> Subject: Re: [mythtv-users] Help with documentation
> 
> On 06/21/2015 06:01 AM, Paul Harrison wrote:
> > Are there any users who would be willing to help bring our
> > documentation up to date?
> >
> > Developers are in general very  bad at documentation which is why we
> > really need some help from someone who has the aptitude for this sort
> > of thing to help us maintain it. It could be one individual or like
> > the translation teams it could be a group of people working together
> > which seems to work well at least for the translations.
> >
> > The main documentation is now in the wiki here
> > https://www.mythtv.org/wiki/MythTV-HOWTO but it is a little out of
> > date. We are also thinking of the idea to add some context help within
> > Myth using the built in web browser widget so for each screen we would
> > need some help text detailing what the screen does and what options
> > are available etc.
> >
> > Paul H.
> Hi Paul
> 
> I am a developer myself and I have done my own documentation. I can help
> out and I am also interested in getting involved in some development
> work on mythtv. See an example of my projects and documentation at
> http://jampal.sf.net and http://pbackup.sf.net/
> 
> We can discuss how to proceed. Let me know if you are interested.
> 
> Peter
> 

I have taken so much from this community that I feel honour
bound to contribute so please include me. 
I have been chipping away at API pages but it’s been slow and it is a
bit of a moving target!

 

A few observations:

 

1.  We need a high
level link for budding authors on ‘how to generate a wiki page’.  I have generated a few pages but cannot for
the life of me remember how I did it. 
Where is that page about sandboxes etc?

 

2. There are a large number of interesting pages in the wiki
which are not accessible by following links. 
The indexing depends upon category tags at the end of the document but unfortunately
these do not get updated in the parent page unless that is opened and re-saved.  Permissions don’t always allow that.  I think it’s exacerbated by local caching or maybe
whether the author is logged in.  He/she sees
the parent updated but nobody else does. 
   Can that be automated or documented?   If there is there a way of listing those and going through them (and also the 'wanted' pages) as a 'start from the bottom' approach?

 

3. What’s a good mechanism for authors and developers to
communicate?  A new group under https://forum.mythtv.org/ perhaps? How do
developers communicate?

 

4. I have often thought that some of the pages describe a
lot of work done by some dedicated contributors and that there is something
very valuable there.  Unfortunately, it’s
often very difficult to work out what it does. 
The commercial world I full of ‘it brings you happiness' but does not say how and
Mythtv is sometimes the opposite – ‘here is the technical’ but no ‘what it does’.  Sorting that may need considerable tact!

 

5. I’ve seen a few pages where I recognise a shortcoming and/or
know that it’s wrong but don’t know how to improve it.   Is there a mechanism for asking the author of that page to review it?

 

6.  A bit of an
aside:  I read these discussions on
Gossamer threads but respond via hotmail. 
Matching the two is not always easy, especially if I have had a hotmail
tidy-up. Is there a more intuitive interface?

 

RegardsPhil

  		 	   		  
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mythtv.org/pipermail/mythtv-users/attachments/20150704/ec7fed9e/attachment.html>