Difference between revisions of "User Manual:Editing the user manual"
m (User Manual 2f Adminis Trivia moved to User Manual:Administrivia) |
(Add navigation between the sections.) |
||
| Line 1: | Line 1: | ||
| − | = Adminstrivia = | + | {{Navigate||User Manual:Index|}} |
| + | |||
| + | == Adminstrivia == | ||
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. | 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. | ||
| Line 5: | Line 7: | ||
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. :-} | 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. :-} | ||
| − | = Dating things = | + | == 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." | 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." | ||
| Line 11: | Line 13: | ||
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. | ||
| − | = Moving Day = | + | == 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. | 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 == |
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. | ||
Revision as of 17:20, 9 February 2006
| Previous | Up | Next |
|---|---|---|
 [[]] |
 User Manual:Index |
[[]] 
|
Adminstrivia
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.
