As our documentation moves to a wiki format to encourage more frequent updates and contributions from department members outside Systems Staff, agreeing upon style guidelines becomes important to ensure that the wiki articles are consistent and act as a cohesive unit. Here's a working list of general guidelines for contributions.
Using subsections to auto-generate tables of contents
Medium and large articles should be broken into subsections using MediaWiki's section heading notation. In addition to establishing a consistent convention for organizing pieces of articles, it also allows for automatic generation of tables of contents like the one on this page. If you use section heading dividers in an article, a hyperlinked table of contents will show up automatically, which makes navigation much easier for the reader.
Bulleted and numbered lists
We often need to provide step-by-step instructions or item lists in our documentation. Use MediaWiki's bullet (*) and numbered list (#) notations to denote separate items. If ordering of the list is critical (first do A, then do B), use a numbered list; otherwise, use bullets.
Use code blocks when providing command-line examples or text file snippets. Prepend each line you want to appear in a text box with a space (this goes for blank lines too, if you want to embed a blank line within your code block).
I am an example code block with an embedded blank line.
General documentation guidelines
Favor short, bullet-point explanations over lengthy paragraphs. Where a complex issue is covered, consider breaking topics out into "Quick Start" and sections for more detailed/advanced topics.
Use stubs / TODO notes
Don't have time to write all the sections of your article? It's a good idea to still add skeleton headings for content you'd like to add later, or have others contribute. These can help you quickly recall where you were in the writing process and give others a good idea of contributions that could be made.
For things you intend to add/edit, you might write "TODO" or "UPDATE" lines like:
- TODO: Fill in instructions for users connecting to this service from off-grounds. --jlg9n
- UPDATE: Remove outdated data about mail client setup; provide how-to on using ITC for mail service. --jlg9n
Want others to contribute particular content? Invite it explicitly:
- Please help us improve this page - contribute feedback on your experience with dual-display configuration for ATI cards here.
Avoid creating articles that are so long that the reader has to scroll through several screens worth of content - break them into smaller articles. Use your best judgment, though, Goldilocks! If an article consumes a small fraction of a screen, consider whether it could be lumped into another related article.
For screenshots, PNG or GIF files are almost always preferable to JPG's. JPG files are are best reserved for photographs with lots of color detail and result in snowy-looking "JPG compression artifacts" surrounding text. Here's an example of an image that should not be a JPG.
As with any page published to the web, avoid writing out email addresses in text, as they can be harvested by spammers' web bots.
For consistency, capitalize all major words in article titles, but not article headings and subheadings. Why? Kind of arbitrary... it's just how we started out originally, so we might as well stick with it.