Best Practices:Community Portal

The community portal will serve two purposes: to provide a place for large-scale metaconversation about how the site ought to work and be run, and to provide a place for the dissemination of some philosophy about how best to work with the tools and limitations of the wiki site management style.

For now, at least, please treat the suggestions on this page as operational policy, just so we've got one. I'm certainly open to discussion about any aspect thereof, on the talk page.

= How To =

To make the results of the work we put into this site useful, and to make it easily manageable, some groundrules and suggestions are probably useful.

Sign Up
To the maximum extent possible, everyone who contributes to the site should create an account, and remember to log in to it everytime they do something. Since this site exists to provide deeply technical advice, and our goal is to become an important source for that advice, provenance is crucial to our readers, so that they can decide what weight to give to any given piece of writing.

Set Up a User Page
After you've set up an account, go to your user page, and put something in there, so that readers can get a sense of who you are as it relates to this technical domain. This might be as simple as a link to, or copy of, your current CV, or a publication biography, or you can take whatever approach to it you like, as long as it's clear to readers from the material what weight they can reasonably assign to your contributions.

Writing for a Wiki
There's a nice tutorial about how to write for Mediawikiae over at Wikipedia:Tutorial, and a markup syntax guide at Wikipedia:How_to_edit_a_page. Here's the short list of hints:


 * Please do *not* use CamelCase linkage when creating new pages; MediaWiki prefers free links, and for several good reasons.
 * They look better
 * They index better with search engines
 * Favor section headers over bullets, except in tables
 * Stack links on a line in tables of contents
 * Use --~ to sign comments on talk pages and the like
 * Don't put a section header at the top of the page; the material that precedes the first one is the page lede and precedes the table of contents; all pages should have one
 * As you're writing, keep your eyes open for words and phrases that should link to their own page for subtopics, or glossary definitions; put the links in even if you don't plan to fill the new pages in (immediately or otherwise).
 * Check back here frequently for new hints, as I watch new wiki users make old mistakes. :-)
 * Check back here frequently for new hints, as I watch new wiki users make old mistakes. :-)

Oh, and try to remember the old Fidonet rule:


 * Be ye not overly annoying, nor too easily annoyed.

Or, in Wikipedia parlance: Assume good faith.

And, finally, if you're feeling helpful and bored, check out Special:Wantedpages to see if there's a topic you can fill in. This is an automagically generated list of links people have left in their contributions which point to pages which don't exist yet. Think of it as the "requests" list, and free free to include such requests in your own material.

If you want to practice, use the Sandbox.

Adding a New Page
Just make a link for it from the main page, with whatever name you like (short names, between 3 and 6 words, are best, except for definition pages, which are usually for 1 to 3 word phrases), and then click through that link.

If you're not sure where to put it in the topic index, put it in "New Material" at the bottom, and someone will come along and move it shortly.

Use the Summary Comments
One of the major strengths of the wiki engine, aside from the easy markup and editing management, is the CVS-like revision tracking system which is built in to the software. The most important part of that is the revision summary comment field below the text edit window.

Please try to put a comment in that, equivalent to what you'd tell CVS when working on code, every time you write or edit a page. It's important. Really. :-)

Talk Pages
Each subject page has a companion Talk page, reachable by the 'Discussion' link at (usually) the top of the page. If you want to hold a meta-discussion about the contents or format of a page, that's the place to go.

User Talk Pages
Each user has a talk page, as well, and they'll be notified when next they log in if you leave a note there for them. This isn't the best format for long, structured discussions, but it's useful for an occasional comment.

Information Taxonomy
If you have a piece to write: write it. Be Bold! If you're not sure where it belongs in the topic tree, don't worry about it, just give it a good 3 to 6 word title and put it under As Yet Unclassified; we'll try to put it in an appropriate place.

Viewpoint
Wikipedia has a policy called NPOV, or Neutral Point Of View to which they encourage writers to adhere. Given the nature of the material which is likely to appear on Best Practices, I don't believe that approach will really work here, but we do have to have a way of disambiguating different approaches, some of which may conflict, but all of which may have some value.

My two initial approaches to this are the commenting protocol started by billn: indent and tag your comments with your user name.


 * Baylink says: like this.

And secondly, use level 2 or 3 headers to separate sections which take different approaches to a given topic or subtopic (but keep them all on the same page), and tag them


 * Approach: This Is How I Do It

or


 * Case Study: Printing at Cisco

or whatever. This way, people with differing ideas can make those ideas known without too much conflict (if we're lucky).

Watch Your Topics
And the site in general, come to that. Keep an eye on RecentChanges, and note that that page can be taken as an RSS or Atom feed as well; check the bottom of the right sidebar.

Collected References
And, finally, if you can remember, try to add links to external sites you reference also to the Collected References page.

= What Not To =

Initally, at least, my goal for this site is to assemble as much raw information as possible, without too much concern as to how it fits into a table of contents. The taxonomy of a wiki site is very malleable, so not as much attention need be paid to how information is laid out when it's created... with one exception: if you're going to go into detail on a subtopic, wiki-link the word or phrase, and put that detail on it's own page. That way, other writers can leverage that writing as glossary-background in their own pages as well.

In fact, if you chose your page name well, they don't even have to look; the information will simply be In The Right Place.

But it's important to remember that this site's goal is right up there in it's name: Best Practices. We're looking for *experience* -- if you haven't deployed a package, beat it to death, and smeared yourself in the ashes, don't write it up here. :-) (On the other hand, though, if you don't understand something, and some spot in either the table of contents or some other page looks like a good place to wiki-link a word or phrase in hopes that someone will fill in that hole, go right ahead and do that.)

Conversely, if you like it or don't like it, whether it's a software package (commercial or F/OSS), a book, a magazine, or website, or something else, let us know.


 * Baylink says: if you do put in things which are clearly opinion, set them off like this, so it's obvious 'who sez'.

The other thing I'd like everyone who contributes not to do is get upset if I refactor the material you contribute, -- mostly this will be breaking information out onto a subpage, or changing around the master index.

I don't claim to be a wiki or information-architecture expert, but I do have 6-8 months experience watching other people do it, and since I can't run big networks, I have to do something. :-)

If I change something, and it bothers you, let me know.

= What's Next =

For the next couple of weeks, I want to keep the wiki under wraps, to the extent you can do that with a public website, so that the collection of information and indexing has some time to gel. I feel that this will make it easier for newly arriving readers and contributors to get a feeling for what's here, what should be here, how to find it, and what else needs to be contributed.

Original writing is wonderful. Contributions of already-written original material are fine as long as a) you wrote them, and b) you don't object to their being distributed under the wiki's license, the choice of which is still in flux. I'm leaning to dual licensure under the GPL and the CC-WIKI license, and discussion should go here.

= Where do we go... from here =

You need to get your security sorted out methinks!


 * Youthinks incorrectly. It's a wiki. --Baylink 16:33, 29 May 2005 (UTC)