User Manual:Editing the user manual
|User Manual:Technical Details||User Manual:Index|
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.
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)