Help:Style Guidelines

Revision as of 17:21, 1 August 2011

The KISS principle

FreeBSD administration is a huge and overarching topic. But the goal of this wiki is to make it accessible, and accessibility means taking it in short and sweet bites - so wherever possible, try to keep your articles short; no more than one or two screen-pages. If that seems impossible, consider breaking your article down into sub-articles - for example, if you're writing an article about securing a server in an internet context, don't go into how to set up an IPFW firewall inside that article, instead link to an IPFW how-to when you get to that point.

Use Section markup tools for complex topics

In some cases - for example, an article on how to set up a Samba server from scratch - it's impossible to keep the overall article length down to a mere screen or two of text. There's just too much to cover, and it really doesn't lend itself well to multiple articles. When you have this type of content to cover, and multiple articles don't make sense, use Section markup! Not only will they automatically make your section titles nice and bold, any article with more than three Sections will also automatically get a hyperlinked table of contents at the head of the article itself. To use Sections, simply type a single line beginning and ending with ==, like this:

==This is an example of a Section line.==

This is how the article you're reading right now is formatted.

How to show text from a console session

When showing an interactive console session, please use a leading space in front of every line (to put the session in a little "box" in the article when it renders) and use the triple-singlequote (''') wikitag to bold user-entered text. For example:

ph34r# this is what a console session should look like on the BSDwiki.
this: Command not found.
ph34r#