Difference between revisions of "Documentation suggestions"

From MythTV Official Wiki
Jump to: navigation, search
m
 
(One intermediate revision by one user not shown)
Line 1: Line 1:
Documentation always has room for improvement and often lags behind features. Good documentation is important for any project to help new users and developers to get started. Which is important for MythTV to grow and improve.  
+
Documentation always has room for improvement and often lags behind features. Good documentation is important for any project to help new users and developers to get started, which is important for MythTV to grow and improve.  
  
Here are a few suggested starting points. This list is not an official statement of what should be done on our documentation, just a list of important and useful things. We welcome your contributions, and if you can think of things to add to the list than please do.
+
Here are a few suggested starting points. This list is not an official statement of what should be done on our documentation, just a list of important and useful things. We welcome your contributions, and if you can think of things to add to the list, then please do.
  
  
==Wiki based Manual==
+
==Wiki-based Manual==
  
* The User Manual project is picking up steam. Contribute to [[User_Manual:Index | the manual]]. The manual is available via the wiki pages, if you are not familiar with '''using a wiki''' than you can learn it in no-time '''[[Help:Contents | here]]'''. Below you'll find a summary of things that needs to be done in this manual.  
+
* The User Manual project is picking up steam. Contribute to [[User_Manual:Index | the manual]]. The manual is available via the wiki pages, if you are not familiar with '''using a wiki''' than you can learn it in no time '''[[Help:Contents | here at the Help page]]'''. Below you'll find a summary of things that need to be done in this manual.  
  
  
The following list contains documentation stuff we need to work on. Please update this list if you have completed something our start working on a task. The list is orderd from important to less important (not important stuff should not be mentioned ;) ).
+
The following list contains documentation stuff we need to work on. Please update this list if you have completed something or start working on a task. The list is orderd from important to less important (not important stuff should not be mentioned ;) ).
  
# The chapter about DVB-C in the wiki-manual needs work, its empty.  
+
# The [[User Manual:Setting up DVB-C (cable)|chapter about DVB-C (cable)]] in the wiki-manual needs work; it's empty.  
# The chapter about DVB-T in the wiki-manual just about done, maybe needs some screenshots?  
+
# The [[User Manual:Setting up DVB-T (terrestrial)|chapter about DVB-T (terrestrial)]] in the wiki-manual just about done, maybe needs some screenshots?  
# The chapter about IP-TV in the wiki-manual needs work, its empty at the moment.
+
# The [[User_Manual:Setting_up_IPTV_(Internet_Protocol_Television)|chapter about IP-TV (Internet_Protocol_Television)]] in the wiki-manual needs work; it's empty at the moment.
  
  
'''quickstart chapter'''
+
'''Quickstart Chapter'''
quickstart chapter needs to be added to tell the reader what to read/not to read when you just want to get mythTV up and running. e.g. could be a short description how to quickly walk through the manual without the need to read to much. This works better than a separate chapter with redundant data because this needs to be maintained and the reader can better find surrounding information about an quickstart topic.
+
Quickstart Chapter needs to be added to tell the reader what to read/not to read when you just want to get MythTV up and running. E.g. this could be a short description of how to quickly walk through the manual without the need to read too much. This works better than a separate chapter with redundant data because this needs to be maintained and the reader can better find surrounding information about a quickstart topic.
  
 
installing > configuring > using
 
installing > configuring > using
  
of course someone who needs to setup a dvb-s device does not need to read the chapter about analogue cards. Both do need to read the chapter about setting up capture cards in general. this needs to be
+
of course someone who needs to setup a dvb-s device does not need to read the chapter about analogue cards. Both do need to read the chapter about setting up capture cards in general.  
  
 
I think to go about this we need some sort of structure (i.e. basic topics), then go through the manual, finding and adding chapters/paragraphs where necessary.
 
I think to go about this we need some sort of structure (i.e. basic topics), then go through the manual, finding and adding chapters/paragraphs where necessary.
  
 
'''Add reading signs'''
 
'''Add reading signs'''
need to add reader signs to chapters and paragraphs so a reader knows if he needs to read it. Need to add the following reading signs:
+
We need to add reader signs to chapters and paragraphs so a reader knows if he needs to read it. Need to add the following reading signs:
 
* no mark:  
 
* no mark:  
 
* Information: nice to know but not necessary for setting up/working with MythTV
 
* Information: nice to know but not necessary for setting up/working with MythTV
Line 35: Line 35:
 
==Screenshots==
 
==Screenshots==
  
* ''Screenshots'' - Screenshots are important for new users to get familiar with MythTV. The [[Screenshots]] page needs to be fleshed out, preferably illustrating the default theme as well as a couple of others, and at least one widescreen. Where possible it would be good to add short notes beside the screenshots to help visitors understand them correctly.
+
* ''Screenshots'' - Screenshots are important for new users to get familiar with MythTV. The [[Screenshots]] page needs to be fleshed out, preferably illustrating the default theme as well as a couple of others, and at least one widescreen theme. Where possible it would be good to add short notes beside the screenshots to help visitors understand them correctly.
  
  
Line 41: Line 41:
  
 
* ''Wiki'' - The '''[[Main_Page | wiki]]''' contains al the information that should not be in the user manual. keeping the wiki pages up-to-date helps users and developers to find the right information.
 
* ''Wiki'' - The '''[[Main_Page | wiki]]''' contains al the information that should not be in the user manual. keeping the wiki pages up-to-date helps users and developers to find the right information.
 
 
The following list contains documentation stuff we need to work on. Please update this list if you have completed something our start working on a task. The list is orderd from important to less important (not important stuff should not be mentioned ;) ).
 
  
  

Latest revision as of 02:38, 29 February 2012

Documentation always has room for improvement and often lags behind features. Good documentation is important for any project to help new users and developers to get started, which is important for MythTV to grow and improve.

Here are a few suggested starting points. This list is not an official statement of what should be done on our documentation, just a list of important and useful things. We welcome your contributions, and if you can think of things to add to the list, then please do.


Wiki-based Manual

  • The User Manual project is picking up steam. Contribute to the manual. The manual is available via the wiki pages, if you are not familiar with using a wiki than you can learn it in no time here at the Help page. Below you'll find a summary of things that need to be done in this manual.


The following list contains documentation stuff we need to work on. Please update this list if you have completed something or start working on a task. The list is orderd from important to less important (not important stuff should not be mentioned ;) ).

  1. The chapter about DVB-C (cable) in the wiki-manual needs work; it's empty.
  2. The chapter about DVB-T (terrestrial) in the wiki-manual just about done, maybe needs some screenshots?
  3. The chapter about IP-TV (Internet_Protocol_Television) in the wiki-manual needs work; it's empty at the moment.


Quickstart Chapter Quickstart Chapter needs to be added to tell the reader what to read/not to read when you just want to get MythTV up and running. E.g. this could be a short description of how to quickly walk through the manual without the need to read too much. This works better than a separate chapter with redundant data because this needs to be maintained and the reader can better find surrounding information about a quickstart topic.

installing > configuring > using

of course someone who needs to setup a dvb-s device does not need to read the chapter about analogue cards. Both do need to read the chapter about setting up capture cards in general.

I think to go about this we need some sort of structure (i.e. basic topics), then go through the manual, finding and adding chapters/paragraphs where necessary.

Add reading signs We need to add reader signs to chapters and paragraphs so a reader knows if he needs to read it. Need to add the following reading signs:

  • no mark:
  • Information: nice to know but not necessary for setting up/working with MythTV
  • Advanced: not for beginning MythTV users
  • QuickStart: Chapter of paragraph is part of the quickstart guide.


Screenshots

  • Screenshots - Screenshots are important for new users to get familiar with MythTV. The Screenshots page needs to be fleshed out, preferably illustrating the default theme as well as a couple of others, and at least one widescreen theme. Where possible it would be good to add short notes beside the screenshots to help visitors understand them correctly.


Misc stuff on the Wiki

  • Wiki - The wiki contains al the information that should not be in the user manual. keeping the wiki pages up-to-date helps users and developers to find the right information.


FAQ

The FAQ list needs a few revisions.


  1. ...
  2. ...