User Manual:Editing the user manual

From MythTV Official Wiki
Revision as of 16:03, 14 August 2005 by

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search


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.  :-}

Dating 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.

Moving Day

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

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.