Difference between revisions of "User Manual:Editing the user manual"

From MythTV Official Wiki
Jump to: navigation, search
m
Line 4: Line 4:
  
  
== About ==
+
Following you'll find a list of guidelines for writing/maintaining the manual. These are here to help the manual stay organized.
  
This section exists to provide an anchor for meta-discussions about the manual itself; things which need to be hashed out, but not in-line where they'll confuse readers.
 
  
I hope that this branch of the wiki will pick up a following, and that everyone will Just Dive In making changes, like folks do over at [http://www.wikipedia.com [[Wiki Pedia]]]... and that I dont offend anyone by hanging out here a lot myself and trying to polish up English and suchlike. :-}
+
''' Don't use hyperlinks ''' - The manual should be readable without the need to hyperjump anywhere. If you want to let the user know about some urls than write it out completly so it stays usable in printed form as wel.  
  
== Dating things ==
+
''' Keep in mind not everyone is a Linux expert''' - When writing manuals you should keep in mind that you have more expertise than most readers. So try to keep it simple without to much technical jargon. Technical solutions can be add to the chaptergroup for advanced users.
  
One thing I feel is important in the maintenance of this manual will be to date and version number mark comments whenever it seems necessary -- particularly things like "It doesn't do X (yet)." or "Y is supposed to work, but doesn't."
+
''' Mark/date things ''' - One thing I feel is important in the maintenance of this manual will be to date and version number mark comments whenever it seems necessary -- particularly things like "It doesn't do X (yet)." or "Y is supposed to work, but doesn't."
  
 
While All Hail Isaac, and I wouldn't want him to feel dissed by anything he reads here, I think accuracy, currency, and clarity are essential for documentation, precisely so that readers can evaluate what they read, in case a branch isn't maintained as up-to-date as might be nice.
 
While All Hail Isaac, and I wouldn't want him to feel dissed by anything he reads here, I think accuracy, currency, and clarity are essential for documentation, precisely so that readers can evaluate what they read, in case a branch isn't maintained as up-to-date as might be nice.
  
== Screenshots ==
+
==== Screenshots ====
  
 
If you want to do screenshots of live TV you must turn off XV video acceleration; you can use the following command to run Mythfrontend.
 
If you want to do screenshots of live TV you must turn off XV video acceleration; you can use the following command to run Mythfrontend.
Line 24: Line 23:
 
This does software rendering of the video stream, so it is slow. To slightly improve speed, make sure you don't have any [[deinterlacing]] turned on.
 
This does software rendering of the video stream, so it is slow. To slightly improve speed, make sure you don't have any [[deinterlacing]] turned on.
  
== Moving Day ==
+
==== Todo ====
 +
 
 +
This section exists to provide an anchor for meta-discussions about the manual itself; things which need to be hashed out, but not in-line where they'll confuse readers.
 +
 
 +
I hope that this branch of the wiki will pick up a following, and that everyone will Just Dive In making changes, like folks do over at [http://www.wikipedia.com [[Wiki Pedia]]]... and that I dont offend anyone by hanging out here a lot myself and trying to polish up English and suchlike.  :-}
  
Over the next day or so, I'll be moving these pages to subpages, where I should have put them in the first place.
 
  
 +
==== Sub Page Protocol ====
  
== Sub Page Protocol ==
+
Over the next day or so, I'll be moving these pages to subpages, where I should have put them in the first place.
  
 
And therein lies a story.  I'm realizing, as I go along, that putting things on subpages, to avoid cluttering the namespace, has the side effect of making them *much* harder to reference conveniently, which is pretty much the precise purpose of using a Wiki to get the work done in the first place.  So, while large chunks of inline text will play well as subpages, smaller self-contained ones which are likely to be cross-referred from other places (like the individual tables in the SQL database reference) probably *should* be independent pages.
 
And therein lies a story.  I'm realizing, as I go along, that putting things on subpages, to avoid cluttering the namespace, has the side effect of making them *much* harder to reference conveniently, which is pretty much the precise purpose of using a Wiki to get the work done in the first place.  So, while large chunks of inline text will play well as subpages, smaller self-contained ones which are likely to be cross-referred from other places (like the individual tables in the SQL database reference) probably *should* be independent pages.
Line 46: Line 49:
  
 
The [[User_Manual:Detailed_configuration_Frontend]] page is shaping up to be enormous (and unwieldy).  It seems like it should be broken up into several pages (though that would make it inconsistent with [[User_Manual:Detailed_configuration_Backend]]).  Maybe at least the stuff in the setup menus should be on a separate page from all of the other frontend stuff? <br>[[User:Psicard|Paul]] 05:34, 13 February 2006 (UTC)
 
The [[User_Manual:Detailed_configuration_Frontend]] page is shaping up to be enormous (and unwieldy).  It seems like it should be broken up into several pages (though that would make it inconsistent with [[User_Manual:Detailed_configuration_Backend]]).  Maybe at least the stuff in the setup menus should be on a separate page from all of the other frontend stuff? <br>[[User:Psicard|Paul]] 05:34, 13 February 2006 (UTC)
 +
 +
  
 
Is there somewhere the entire User Manual can be downloaded as a .pdf?  Thanks.
 
Is there somewhere the entire User Manual can be downloaded as a .pdf?  Thanks.

Revision as of 12:47, 5 September 2008

Previous Up
Go-prev.png User Manual:Technical Details Go-up.png User Manual:Index


This page is up-to-date to MythTV version 0.20


Following you'll find a list of guidelines for writing/maintaining the manual. These are here to help the manual stay organized.


Don't use hyperlinks - The manual should be readable without the need to hyperjump anywhere. If you want to let the user know about some urls than write it out completly so it stays usable in printed form as wel.

Keep in mind not everyone is a Linux expert - When writing manuals you should keep in mind that you have more expertise than most readers. So try to keep it simple without to much technical jargon. Technical solutions can be add to the chaptergroup for advanced users.

Mark/date things - One thing I feel is important in the maintenance of this manual will be to date and version number mark comments whenever it seems necessary -- particularly things like "It doesn't do X (yet)." or "Y is supposed to work, but doesn't."

While All Hail Isaac, and I wouldn't want him to feel dissed by anything he reads here, I think accuracy, currency, and clarity are essential for documentation, precisely so that readers can evaluate what they read, in case a branch isn't maintained as up-to-date as might be nice.

Screenshots

If you want to do screenshots of live TV you must turn off XV video acceleration; you can use the following command to run Mythfrontend.

$ NO_XV=1 mythfrontend

This does software rendering of the video stream, so it is slow. To slightly improve speed, make sure you don't have any deinterlacing turned on.

Todo

This section exists to provide an anchor for meta-discussions about the manual itself; things which need to be hashed out, but not in-line where they'll confuse readers.

I hope that this branch of the wiki will pick up a following, and that everyone will Just Dive In making changes, like folks do over at Wiki Pedia... and that I dont offend anyone by hanging out here a lot myself and trying to polish up English and suchlike.  :-}


Sub Page Protocol

Over the next day or so, I'll be moving these pages to subpages, where I should have put them in the first place.

And therein lies a story. I'm realizing, as I go along, that putting things on subpages, to avoid cluttering the namespace, has the side effect of making them *much* harder to reference conveniently, which is pretty much the precise purpose of using a Wiki to get the work done in the first place. So, while large chunks of inline text will play well as subpages, smaller self-contained ones which are likely to be cross-referred from other places (like the individual tables in the SQL database reference) probably *should* be independent pages.

It's a pretty rough haul, figuring out how to factor the page/subpage issue; this seems like a good topic for discussion.


Put it here.  ;-)


And I've attracted help already. Hey, JDonavan; nice stuff. You don't seem to have a user page yet, so I'll post this here, and hope you note it in recent changes.


JD- The user manual is something I'd hoped to see out of the wiki since it started. Happy to help.


The User_Manual:Detailed_configuration_Frontend page is shaping up to be enormous (and unwieldy). It seems like it should be broken up into several pages (though that would make it inconsistent with User_Manual:Detailed_configuration_Backend). Maybe at least the stuff in the setup menus should be on a separate page from all of the other frontend stuff?
Paul 05:34, 13 February 2006 (UTC)


Is there somewhere the entire User Manual can be downloaded as a .pdf? Thanks.


Previous Up
Go-prev.png User Manual:Technical Details Go-up.png User Manual:Index