Difference between revisions of "User Manual:Editing the user manual"
m (User Manual 2f Adminis Trivia moved to User Manual:Administrivia)
Revision as of 17:21, 11 January 2006
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. :-}
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.
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.