Difference between revisions of "User Manual:Editing the user manual"
m |
|||
| (10 intermediate revisions by 5 users not shown) | |||
| Line 1: | Line 1: | ||
| − | {{ | + | {{User Manual TOC}} |
| − | + | This page is up-to-date to MythTV version 0.20, the current release is {{CurrentRelease}} | |
| + | |||
| + | |||
| + | 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 for hyperjumps. If you want to inform users about urls, write them out out completely so it stays usable in printed form as wel. | |
| − | + | '''Not everyone is a Linux geek''' - Remember you have more expertise than most readers; keep it simple and avoid technical jargon. Technical solutions can be added to the chaptergroup for advanced users. | |
| − | + | ''' Mark/date things ''' - Comments should be dated and marked with version numbers -- particularly things like "It doesn't do X (yet)." or "Y is supposed to work, but doesn't." | |
| − | + | Accuracy, currency, and clarity are essential for documentation, precisely so that readers can evaluate what they read, in case a branch is less up-to-date than it should be. | |
| − | == 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 21: | 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. | ||
| − | == | + | ==== 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 Wikipedia]... and that I don't 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. | 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 44: | 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. | |
Latest revision as of 01:30, 18 October 2010
This page is up-to-date to MythTV version 0.20, the current release is 34.0
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 for hyperjumps. If you want to inform users about urls, write them out out completely so it stays usable in printed form as wel.
Not everyone is a Linux geek - Remember you have more expertise than most readers; keep it simple and avoid technical jargon. Technical solutions can be added to the chaptergroup for advanced users.
Mark/date things - Comments should be dated and marked with version numbers -- particularly things like "It doesn't do X (yet)." or "Y is supposed to work, but doesn't."
Accuracy, currency, and clarity are essential for documentation, precisely so that readers can evaluate what they read, in case a branch is less up-to-date than it should be.
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 Wikipedia... and that I don't 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.
