Wiki Style Guide

From Mugshot Developer Wiki

Here are some general style guidelines for this developer wiki, these are just meant as reminders. The generic MediaWiki documentation is much more complete, see the editor help page and markup guide.

Overall Site Organization

See also the Site Map.

• Two important kinds of page
  • Reference pages which contain relatively static overviews or definitions or HOWTO guides; think of these pages as associated with a concept or technology
  • Activity pages which are conversation centers or project management/coordination hubs; think of these pages as associated with a group of people working together. They should link to relevant reference pages (which may be shared among activities)
• Activity pages tend to be either about a user experience design project or a coding project; try to keep these clear and separate, e.g. Web Swarm or Friends And Groups would be user experiences, while Server and Linux Client are codebases that implement those experiences.
• Activity pages should be relatively short; a long discussion of a topic, full brainstorm transcript, etc. should go on a separate page then be linked in.
• Activity pages should tell a story about the design process used for the activity - it can be "7 suggested steps compliant" if you did it that way, or if you didn't, tell the accurate story.
• Reference pages that define a potentially-unclear term should be in the Glossary category
• Reference pages about engineering implementation topics are in the Development category
• HOWTO guides on setting up development environments are in the Development Setup category
• Style guides for e.g. Java or C++ coding are in the Style Guide category
• Each page should link to relevant reference pages, for example if I talk about EJB3 I'd make it a link to the definition of EJB3
• Create User pages in the User: namespace, not Bryan Clark see User:Clarkbw

Stylistic Stuff

• Use capitalized words where it makes sense
  • ex. Information Site, not Information site or information site
  • [[information site]] goes to [[Information site]] which is different from [[Information Site]] use a redirect for the [[Information site]] page if it makes sense
  • Use the redirects to avoid always entering the [[Information Site|information site]] links everywhere, save yourself some effort

• Use spaces between words, don't use studly caps to remove spacing
  • ex. Information Site, not InformationSite

• Don't be too verbose on each page
  • Link to other helpful pages when you can

• Use links to define obtuse terms
  • The Category:Glossary should be included on term definitions

MediaWiki Tips

Generic MediaWiki docs at the editor help page and markup guide.

A number of the config options have questionable defaults; you might want to change some, some common ones to change:

• User profile
  • Enable "E-mail me on page changes" so you get email on watched pages instead of having to check "my watchlist" on the web site
• Date and time
  • Set the time zone offset
• Editing
  • Enable "Add pages I create to my watchlist"
  • Enable "Add pages I edit to my watchlist"
• Search
  • Add Template and Category to default searches
• Misc
  • Underline links can be set to Always if you have trouble seeing the links by color alone