Day 25 - Wikis and Documentation Part 2

Intro

This article is part two of a two part series and a collaboration between Brandon Burton and Philip J. Hollenback where they explore the problems with Mediawiki, the challenges of writing good documentation with today's tools, improvements that Brandon has implemented, and ideas for further improvements.

In part two, we focus on overcoming Mediawiki's poor defaults by covering existing improvements that Brandon has implemented at work and exploring a number of additional ideas for ways to improve it further.

Things I've implemented at work

As I mentioned, I have implemented a number of improvements to the Mediawiki installation at work, they fall into two categories.

1. Visual Improvements
2. Layout/Style Improvements

Visual Improvements

The first you'll notice about a default Mediawiki installation is that is ugly, it's very Web 1.0 in all the worst ways. I chose to improve on this with four things

1. A better theme
2. Tweaking the fonts
3. Tweaking the URL colors
4. Finding some better CSS for the tables, as we use tables heavily

Theme

Choosing a visually appealing, but not crazy, theme is very important. I chose the daddio because it has a simple color scheme and the shiny blue in the navigation bar adds some pop but doesn't distract. I also liked how it put the User links at the top as a navigation aid. This particular design choice offers a lot of possibilities if you want to do custom navigation along the top.

Fonts

The default font for the daddio theme is just font-family: sans-serif;, which isn't very pleasant to look at for long periods of time. I improved this with font-family: Verdana;. Of course, a picture is worth a thousand words, so -

Before:

After:

URL Colors

I found, and I think most people would agree, that the default URL colors of Mediawiki to be pretty much an eye sore, so I chose to do something a little more pleasant.

There are three main kinds of links in Mediawiki and I adjusted the colors for all three. They are:

1. Visited
2. Normal
3. Page Doesn't exist

By default they have the following colors:

1. Visited = Purple
2. Normal = Dark Blue
3. Page Doesn't Exist = Red

After I finished tweaking them, they were

1. Visited = Dark Green
2. Normal = Light Blue
3. Page Doesn't Exist = Light Orange

Tables

I think that the kind of documentation we produce as systems administrators, and so the kind we produce a lot of at my work, is best formatted in two ways.

1. Lists (Bulleted or Numbered)
2. Tables

I'm a big fan of tables, and having memorized the table syntax for the Mediawiki markup, I use a lot of tables. Unfortunately, the default table style is pretty bad. It didn't take a lot of CSS to fix that though. There isn't much else to say, so I'll show you the difference.

Before:

After:

In the spirit of sharing, I've put the CSS I used and the change I made to the daddio up as a Gist.

Layout/Style Improvements

A default Mediawiki is a wide open thing, and if consistent structure and style is not enforced from the beginning, it becomes a giant pile of chaos.

The two key things we did to prevent these were the creation of:

1. Templates
2. Style Guidelines

Templates

One of the keys to effective documentation and increasing people's likelihood of producing good documentation is consistency. And, as any good systems administrator knows, a key to consistency is templates.

Now, I want to stop and clarify, the templates I'm talking about here are not the Mediawiki templates, but are just pages in Mediawiki with all the markup written, so each user can just copy and paste them as make new pages. I investigated the Mediawiki templates, but they serve a slightly different function from what I was aiming for.

For my work, we have three main types of documentation that we made templates for:

1. Customer Infrastructure
2. Software Specific
3. Procedure Specific

What I did was to make a specific /Templates/ section of our wiki and make a template for each type of documentation. This coupled with a set of guidelines on how we should document, meant that as each of us created a new page, perhaps for a new customer or a new piece of software we've begun using, we just need to edit the template page, Ctrl-A Ctrl-C, change the tab, and Ctrl-V and you've got all your structure in place.

An example of the template we use for software specific page is available as a Gist

Style Guidelines

Finally, we put together some basic guidelines on how we were going to document things. A lot of these ideas came from the OpenSolaris Guidelines, which says

Readers project some significance onto every change in language, tone, or typographic convention. A consistent style enables readers to internalize the language and text conventions of the document. As a result, understanding occurs more easily and significant points stand out more clearly. Consistency is one of the most valuable aspects of good style. In addition, consistency improves clarity for translation purposes.

I'll highlight some of the guidelines we came up with were:

1. Always start from a template.
2. Update the templates as new items that should exist in them are discovered
3. Lists are used to break out information from the paragraph format and to structure the information into an easier-to-read format. Lists must include at least two items. If a list has more than nine items, try to identify a way to divide the list into two or more lists. Use unnumbered (bulleted) lists when the items are not dependent on the sequence in which you present them. When the items are dependent on sequence, use numbered lists with numerals and letters to build the hierarchy.
4. The purpose of many technical documents is to explain how to use a product to accomplish specific tasks. In such documents, detailed instructions on how to accomplish tasks are often provided in the form of procedures. Procedures contain an ordered set of steps.

Those are the steps that we've taken so far to improve our Mediawiki installation, a combination of:

1. Visual Improvements
2. Layout/Style Improvements

Additional ideas

The improvements we've made are by no means the limit of what can be done with Mediawiki. In fact, I have a number of ideas for further improvements:

Extensions

Some of the potential extensions are

1. Dynamic Page List
2. This extension has a simple query language you can use to generate a list from any other wiki content
3. Can be used with either a tag or as a parser function
4. PDF Export
5. Syntax highlighting
6. Make your own
7. Building your own extensions is relatively easily
8. Extensions that query other database or data sources to integrate into your wiki

TODO Tracker

• A TODO is a "bread crumb" that you leave which indicates further action, improvements, etc, that should be done for a specific piece of documentation.

• An example is shown below:

  TODO: Write more detail instructions on how to document DNS records for a customer.

• The idea is that you leave "TODO: foo" whenever there is something left to be done. Then we have an external script which will crawl the wiki and generate a report of Documentation TODOs.

• This allows use to embed the action in the relevant context, but still generate a total view of the actions for assignment and should help guarantee documentation does not grow stale.

Categories

Categories to create "Automagic index pages"

Automation

The pywikipediabot toolkit offers a lot of potential for doing automation.

Conclusion

In conclusion, though wikis have a number of poor defaults and drawbacks and while producing good documentation is difficult, with a good base like Mediawiki, some customizations, and some good guidelines, you can go a long way towards making things easier and more fun to use.

Further Reading

1. Mediawiki Book
2. The Practice of System and Network Administration
3. Writing Great Documentation, what to write
4. Documentation Tips for Sysadmins

Day 24 - Terminal Multiplexers

Written by Jon Heise

In the grand world of the command line and in dealing with servers, persistence is key. To that end, there are ways to run stuff that lives beyond your current ssh session, this article will focus on screen and tmux. These tools help you run shell sessions that persist across logins (among other awesome capabilities).

GNU Screen is by far the older of the two being first released in 1987. Tmux was released much more recently in 2007.

Similarities

First off, let's talk similarities. They both have the core functionality of being able to “detach” a session from active usage by a user. Let's say a user wants to run irssi (an irc client) and detach it - the workflow would be as follows:

Note: screen and tmux are generally controlled by multiple keystrokes. In the examples below, C-a means pressing "control + a" keys. A sequence 'C-a d' means press "control + a", release, then press 'd'. This syntax is common in screen and tmux documentation.

goal	screen	tmux
run irssi	screen -S irc irssi	tmux new irssi
detach	C-a d	C-b d
attach again	screen -r irc	tmux attach

FYI: The default screen command key is C-a, while the default tmux command key is C-b. Most things you do in screen and tmux, by default, will always start by pressing the command key.

The above examples create a screen session called 'irc' and an unnamed tmux session. Both tmux and screen also support multiple terminals in one session, that is, you can run multiple commands in separate windows in the same screen or tmux session.

goal	screen	tmux
create new window	C-a c	C-b c
go to previous window	C-a p	C-b p

Using multiple windows in tmux is a bit easier, by default, as there is an omnipresent status bar at the bottom of the terminal showing open windows.

You can get a list of all known sessions:

screen -ls

tmux ls

That's the basics of each - first: creating, attaching, and detaching sessions, and second: creating new windows in a session.

Differences

Having listed features that they both share, it is time to discuss features that one posses that the other does not.

Screen has special features like serial port support and multiuser access. Screen can directly open serial connections from other machines, network gear, or anything that wants to spew data forward on a serial terminal. This feature can be handy for sysadmins with macbooks that need to configure some network gear as there is no good mac specific terminal emulator software. Connection to a serial port is simple:

screen /dev/ttyN

Additionally, you can share your screen sessions with other users on the system with screen's "multiuser" feature. This allow you to share terminals with remote coworkers to do pair debugging or shadowing without having to use a user shared account. See the screen documentation for the following commands: multiuser and acladd.

Tmux's main feature is the client/server model it uses. Earlier it was mentioned that not being able to specify a specific instance of tmux was less of a nuisance, this is due to the fact that tmux runs in a client server model. As long as there is a session of tmux running (even in the background), the tmux server will exist to manage it. Since there is a central server dealing with each tmux client and session, it is far simpler for the client that the user has launched to be aware of these. If you have multiple tmux sessions running (via tmux new), you can ask any tmux session to list them by typing 'C-b s', the result looks something like this:

From the above session list, you can switch to any other open session.

Until recently, tmux (vs screen) was the only one supporting both vertical and horizontal splits. You can create horizontal splits with C-b " and C-b % for vertical splits. In screen, horizontals are made with C-a S and verticals made with C-a | (pipe).

Tricks

You can nest screens within screens, or tmux within tmux. This is most common when running tmux or screen, sshing to another server, and running screen/tmux from there.

goal	screen	tmux
start up	screen -S main	tmux new -s main
ssh somewhere	ssh ...	ssh ...
create a new session on remote host	screen -S foo	tmux new -s foo

The main problem with nesting is knowing how to talk to the nested session. To detach from the 2nd screen session (nested) you'll have to send 'C-a a' which will send a litteral C-a from the first screen to the running program, which is another screen session. Detaching from the nested screen, then, would be 'C-a a d'

This is similar with tmux, though your tmux may not be configured similarly. You may have to add this to your ~/.tmux.conf:

bind-key C-b send prefix

Now pressing 'C-b C-b d' will detach from the nested tmux

The above only applies if you nest screen-in-screen and tmux-in-tmux. If you have screen-in-tmux, you would just press the normal C-a to talk to screen. Same with tmux.

Making them similar again

Screen's defaults don't usually include a status bar, but you can make one similar to tmux by adding this to your ~/.screenrc:

hardstatus alwayslastline "%w"

You can also tune tmux to behave more like screen by changing the command key. In your ~/.tmux.conf:

set-option -g prefix C-a  # make the command key C-a
unbind-key C-b            # unbind the old command key
bind-key a send-prefix    # 'C-a a' sends literal 'C-a'

Why would you do this? If you've used screen for years, and want some of your muscle memory to function in tmux, doing the above is a good start.

Cheat sheet

In closing, here is a recap of commands in convenient cheat sheet form:

action	screen	tmux
new named session	screen -S foobar	tmux new -s foobar
detach session	`C-a d`	`C-b d`
reattach session	screen -dr foobar	tmux a -t foobar
new terminal	`C-a c`	`C-b c`
next terminal	`C-a a` or `C-a n`	`C-b n`
lock terminal	`C-a x`	lock (from command prompt)
large clock	not supported	`C-b t`
not as good smaller clock	`C-a t`	not supported
split screen horizontal	`C-a S`	`C-b “`
split screen vertical	`C-a |`	`C-b %`
change to other portion of a split	`C-a tab`	`C-b arrowkey` (up or down)
send prefix	`C-a a`	`C-b C-b` (if

Happy tmux'ing and screen'ing!

Further reading:

• tmux homepage
• GNU Screen homepage
• OpenBSD FAQ on tmux

Day 23 - Package vs Config management.

Written by Joshua Timberman

Package management is a best practice in system administration. So is automated configuration management. However, the maintainer scripts run by package management tools are an anti-pattern almost in direct conflict or competition with configuration management systems.

In my examples I'm going to talk about Debian packages and Chef, because that is what I use. Adapt your mindset for your own favorite distribution and configuration management tool.

Server Lifecycle

When almost all the modern, popular Linux distributions were created, servers had a general lifecycle, and an expected supportability throughout that lifecycle. Some distributions have a commercial entity that provides paid support. Others have an excellent user community that volunteers their time to help users and administrators. Many considerations in the development of the Linux distribution stem from the expectation that someone will require support, and the distribution should provide a supportable release. In addition to this, the package's maintainer scripts is what provides additional configuration, such as creating users, or starting services provided by the package.

Package Management

One of the value-adds of most Linux distributions is the package management system. Package management behavior and maintainer scripts are well documented by the distribution to be supportable by a company of support engineers, or a community of volunteers. For system administrators, however, the main reason to use package management is to get some pre-compiled software on the system, and to resolve and install any dependencies that package may have; it is less necessary to have a service start on package install. For example, CouchDB requires Erlang and various other libraries, so the package manager would install those libraries, Erlang and CouchDB. While package management has many other benefits, such as version management, and they can do things like drop off configuration files and start up daemons that were installed. There is definite business value in using packages, and that's why it is a sysadmin best practice.

Many system administrators create their own packages and host them on an internal repository. In most of the environments I've worked in, these packages were as simple as just managing the files included in the package usually ignoring the upstream culture of maintainer scripts and other policies, because the system administrator planned to use a configuration management tool to automate setup and maintenance of the software to run the business application. In these cases, the software provided by the distribution did not meet the needs of the business in some way. Perhaps an application required a newer library version, or you needed to patch in a feature or bug fix, or the default setup of a package conflicted with the way a business application was deployed.

Configuration Management

There are as many different application deployments as there are businesses. The different ways the application stacks are deployed provide a specific business value. The application stack often includes a number of the distribution-provided packages, as well as the code written by the business's software developers.

However, most companies have unique needs when it comes to how the software runs in their environment. Perhaps the HTTP server default configuration isn't properly tuned for the web application that it serves. Maybe the business requires that the MySQL server have replication slaves, and this configuration is not enabled by default. Perhaps the system administrator(s) that run the servers have tuned a particular web server for performance, but it conflicts with another web server package. The actual conflict is based on configuration, not on binaries that are created - both packages by default listen on the same port when the service is started.

For these reasons and more, automated configuration management tools such as Chef are now modern system administration best practice.

The problem we face, is that the packages that we install often run a number of maintenance scripts to ensure that the package is set up and configured. The distribution included the scripts to enforce some policy such as where to put certain configuration files, start services, or where to locate data files created by the packaged software. In some cases, the package maintainer scripts only perform actions when the package is removed (postrm in Debian/Ubuntu), and if there are problems, they don't surface until the package is removed.

Example of the Conflict

To illustrate the conflict between package maintainer scripts and configuration management systems, let's look at a couple use cases with MySQL. We are using Chef to automatically install the mysql-server package on Ubuntu 10.04 LTS running on an instance in Amazon EC2. Our two business requirements are setting a randomly generated root password and move the MySQL data directory to ephemeral storage, as the default location is on a smaller filesystem size. Normally, the package installation on Ubuntu will prompt the user for input on the password, which we then need to work around to automate the package installation. We'll need to generate a preseed file to give the proper settings to the package manager. We install mysql-server on a test system:

sudo apt-get install mysql-server

(And enter a bogus password when prompted, which is what we are trying to avoid).

To get the preseed settings for the package, we need the debconf-get-selections package:

sudo apt-get install debconf-get-selections

Then we get the mysql-server settings for our preseed file:

sudo debconf-get-selections | grep ^mysql-server > mysql-server.seed

We'll use a template that has a generated password (@mysql_root_password), along with the rest of the contents in the file:

mysql-server-5.1 mysql-server/root_password_again select <%= @mysql_root_password %>
mysql-server-5.1 mysql-server/root_password select <%= @mysql_root_password %>

And we set this up with Chef using a template and execute resource:

template "/var/cache/local/preseeding/mysql-server.seed" do
  source "mysql-server.seed.erb"
  owner "root"
  group "root"
  mode "0600"
  notifies :run, "execute[preseed mysql-server]", :immediately
end

execute "preseed mysql-server" do
  command "debconf-set-selections /var/cache/local/preseeding/mysql-server.seed"
  action :nothing
end

Then we have a package resource that installs mysql-server:

package "mysql-server"

Next, we want to configure an alternate location for the MySQL database on the ephemeral storage, as the database size may grow beyond the default root partition size (10G). An example Chef recipe to do this might look like:

service "mysql" do
  action :stop
end

execute "install-mysql" do
  command "mv /var/lib/mysql /mnt/mysql"
  not_if do FileTest.directory?("/mnt/mysql") end
end

directory "/mnt/mysql" do
  owner "mysql"
  group "mysql"
end

mount "/var/lib/mysql" do
  device "/mnt/mysql"
  fstype "none"
  options "bind,rw"
  action :mount
end

service "mysql" do
  action :start
end

We have to stop MySQL, move the directory, and restart MySQL. We use a bind mount so the configuration in /etc/mysql/my.cnf does not need to be changed. If we wanted to do that, there's additional configuration required.

Neither of these scenarios take into account the additional complexity required to manage the Debian system maintenance user set up in the MySQL package, or countless settings possible to set up MySQL tuning parameters, or database formats.

We're forced, here, to do extra work to skirt around problems created by the package management tool trying to be responsible for things outside of packages. The anti-pattern is exacerbated if we have to manage the package and installation on a different OS. Then, we'd have to redo the whole dance for another platform. If our package manager simply dropped the binaries/libraries off and we could handle this configuration directly and much in the configuration management, it would be much easier to manage in a heterogeneous environment.

Conclusion

Package management certainly has value! It allows system administrators to install a base OS image that gives all the hardware support and user-land well known and loved in Unix/Linux systems. When it comes to the application stack required by the business, custom configuration is often required. Package maintainers don't, and can't be expected to, imagine every possible custom configuration. Configuration management tools can, however, be used to cover any custom configuration, since that is their job.

After all, part of the Unix (and Linux) philosophy is that each program should do one thing well.

Further Reading

• Chef
• MySQL Chef Cookbook by Opscode
• Amazon AWS EC2
• Amazon AWS EC2 Instance Sizes
• Debian Policy: Maintainer Scrips
• Unix Philosophy
• Disabling maintiner scripts on Ubuntu - a hack that makes apt-get strip packages of maintainer scripts before they install.

About the author

Joshua Timberman is a Technical Evangelist for Opscode. He has worked for a wide range of companies as a system administrator: from small company IT support to Enterprise web infrastructure delivery for Fortune 500 companies. He helps companies and individuals learn how to use Chef and the Opscode Platform. He wrote the majority of the Chef cookbooks Opscode publishes, teaches the Chef Fundamentals class, and speaks at user groups and conferences. He can be found as jtimberman on Twitter, Skype Freenode, GitHub and more, or via email joshua@opscode.com.

Day 22 - DevOps: Where Are We Now (part 2)

Intro

This article is part two of a two part series by [Brandon Burton][solarce] which explores what [DevOps][devops] is and why it matters, where it has come since Brandon's article in July, and where you should be looking if you want to be involved.

Part two focuses on where DevOps has come since July and where you should be looking if you want to be involved.

What's happened since July

Back in July, I wrote an article entitled DevOps (and Reliam) and why it matters which covered the idea of CAMS, discussed briefly where Reliam sees DevOps fitting into its business, and highlighted a number of resources for following with growth of DevOps. Things have been very busy since then. There has been an explosion of blogs, articles, conferences, user groups, and online discussion about DevOps.

If you're still a little unsure what this DevOps thing is all about, I'd highly recommend you read or revisit the following URLs before digging into the rest of the content in this article.

• What is DevOps all about?
• What DevOps means to me
• What Is This DevOps Thing, Anyway?
• What DevOps Means to Me

Since DevOps is first and foremost about people, the most exciting goings on since July have been the meetups, conference talks, and videos people have been producing.

Meetups and Conferences

There have been a growing number of meetups, including

• Chicago
• Silicon Valley
• New York
• Melbourne
• Atlanta
• Vancouver
• Los Angeles
• Boston
• Sydney
• London
• Vienna

Additionally, we've seen DevOps Days conferences begin being organized, including

• Europe 2010
• Brazil 2010
• USA 2010

Some specific talks and videos

There have been DevOps related talks and videos occurring at meetups and other conferences, some of the ones I found excellent where

• Changing Culture to Enable DevOps
• DevOps for Business - Lessons Learned
• DevOps outside of Web Operations
• DevOps Cafe - London DevOps Roundtable
• DevOps Cafe - Open Mic at Kaching
• Jacob Kaplan-Moss on DevOps

Blog Articles

There have been so many blog articles, but I'll try to highlight a few that I think are worth reading, probably twice.

• DevOps Demystified
• DevOps: The Re-emergance of Systems Engineering as a Discipline
• DevOps the Dyn Inc. way: How we Blend Operations and Engineering
• Enter Stage Right: DevOps
• DevOps is not a technology problem. DevOps is a business problem
• On Discovering DevOp
• The Hollow Hype around DevOps
• Systems Engineers are Software Developers
• Track Every Release
• A new breed of System Engineering

I'm going to highlight all the articles in a series that Matthias Marschall (@mmarschall) just wrapped up, because they are all high quality and must reads (in my opinion)

• Spliffs and Submarines: The Two Cultures and the State of DevOps
• Is DevOps Being Hijacked by Technologists?
• DevOps: State of the Nation
• What DevOps Is Not
• DevOps: cleans and shines without harsh scratching
• DevOps: These Soft Parts
• The State Of DevOps
• The Implications of Infrastructure as Code
• Challenges for the DevOps Crowd
• Approaching Legacy Environment Management with DevOps

Where to go next

So now that you've digested all the awesome DevOps content that's been cranked out since July, you're probably wondering where you should be looking so you can keep up on all the awesome content that's going to be produced in the future. I'm happy to share all the places I'm watching, which span your usual collection of blogs, podcasts, mailing lists, and Twitter.

Mailing Lists/Group Discussion

• DevOps Weekly
• DevOps Google Group
• DevOps Toolchain Google Group
• DevOps LinkedIn Group

Twitter folks to Follow

• @patrickdebois
• @damonedwards
• @allspaw
• @littleidea
• @nasrat
• @kartar
• @cread
• @KrisBuytaert
• @lordcope
• @ripienaar
• @builddoctor
• @botchagalupe
• @mmarschall

And of course, you can follow the #devops hashtag on Twitter.

Blogs to Follow

• Planet DevOps
• Agile Sysadmin
• DevCo
• stochasticresonance
• Kitchen Soap
• dev2ops
• Agile Web Operations
• Just Enough Developed Infrastructure

Podcasts

• DevOps Cafe
• Webpulp.tv
• SysAdministrivia

Summary

In summary, DevOps has seen a lot of activity since July. There has been an explosion of blog posts, meetups, and conferences, particularly in the last couple of months. There are many places to be watching and hopefully you've been able to add a few to your list.

Day 21 - Wikis and Documentation

Intro

This article is part one of a two part series and is a collaboration between Brandon Burton and Philip J. Hollenback where they explore the problems with Wikis, the challenges of writing good documentation with today's tools, improvements to Mediawiki that Brandon has implemented, and ideas for further improvements.

Part one focuses on the problems and challenges.

The problem(s) with Wikis is...

It's a wiki! Wikis are a slightly less-worse alternative to all other documentation and publishing mechanisms. What's the worst thing about wikis? Well...

Here it is, 2010, and guess what? Every wiki works pretty much exactly the same as they did back in 2001 (or, for that matter, back in 1995 when WikiWiki was invented). Why has absolutely no real development happened in the world of wikis? I realize that there may be amazing commercial wikis out there like Microsoft Sharepoint or Confluence, but who uses them? Instead we all blindly set up our own Mediawiki installations over and over again, with all the same annoyances and problems. We are all unquestioning worshippers at the altar of the wiki.

Let's get down to business: here are some of the numerous things wrong with wikis, in no particular order:

CamelCase

This seemed amazing back in 2001 because it allowed you to create your own web pages on the fly. Amazing! However, the really cool thing was the autocreation of web pages, not the mechanism of CamelCase. Camel case was just an easy way to tell early wiki syntax parsers to create a link to a new page. Nine years later, camel case is faintly embarrassing. It's like those pictures from the early 80s where guys all had perms - seemed a good idea at the time. Every single time you try to explain wikis to someone, you have to apologize for how camel case works.

Markup Languages

Wiki markup languages must be amazing and precious, because we have dozens of them to choose from. Seriously? I have to remember whether to write

[[www.hollenback.net][http://www.hollenback.net]]

or

[www.hollenback.net|http://www.hollenback.net]

or

[http://www.hollenback.net www.hollenback.net]

based on which wiki I'm using? That's awesome.

Tables

If you ask 99% of office workers how to create a table, the answer is fire up Excel. Wikis actually manage to make that worse due to the pain of creating tables. The canonical table representation in wikis is vertical bars and spaces, and you better not accidentally add an additional column unless you want to spend 15 minutes tracking down that one extra vertical bar somewhere.

| *this* | *is an* | *awesome table* |
| there | are | many like it | but this one | is mine |

Attaching Images and Documents

Looking for a standard way to drop images into a document? Good luck with that. If you are lucky you can attach an image to a page, assuming you don't accidentally exceed the web server file upload size. Wait, did you also say you want to flow the text around your image? You just made milk come out of my nose. Next you will be asking for the ability to right-justify your image on the page! What is this, QuarkXpress?

Attaching documents to a wiki is just as bad, because most wiki software uses the same horrible upload mechanism. As a bonus, any Excel spreadsheet you attach to a page becomes an inert lump of no-displayable, non-searchable data.

Organizational Structure

We all love really shallow document hierarchies, right? Must be true because that's how every wiki works. Oh sure we all pretend there is a tree structure in wikis but nobody ever uses it. We all end up creating zillions of top-level documents. Which then brings us to the issue of wiki search, which is also essentially nonexistent. Most people cheat and use a domain-specific google search instead, but then you surrender your site to the whims of the almighty google. That means your search mechanism doesn't have any domain-specific optimizations.

The problem with documentation is...

The problem with documentation is that it's a lot of effort to write clear, correct, and usable documentation. It takes time, not just any time, but concentrated, distraction free time. The sort of time that there is never enough of. Further, it takes a plan - a design for serving your intended audience reasonably. It does not help that most of the common tools that are chosen as the repository of the documentation are not very good. Bad tools drain your time. Sadly, this includes the most popular tool (in my experience), wikis, particularly my favorite tool for keeping documentation, Mediawiki.

Documentation + Mediawiki == Maybe better

Having said all that, wikis are still the best widely available documentation solution out there.

Of all the available wikis, Mediawiki is the wiki most commonly chosen, and this is the one that Brandon has had the opportunity to make a number of improvements to.

Since Mediawiki is open source software and just PHP + MySQL + Text + CSS, it is relatively easy to improve how it can be used to keep more effective documentation. I've had the opportunity to make a number of changes to the Mediawiki installation at my day job and I'm going to take part two of this article to share those with you. Additionally, I have some other ideas on how Mediawiki could be improved even further, a number of which have come from reading the Mediawiki book

In part two, we'll explore some improvements that Brandon Burton has implemented at his work and some ideas Brandon and Philip have for further improvements.

Day 20 - Github Gist

This article was written by Phil Hollenback (@philiph)

I assume everyone is familiar with the idea of a pastebin - a website for sharing text fragments with an emphasis on code fragments. Pastebins have been around since 2002, according to Wikipedia. They're an incredibly useful resource for sharing textual data and are something we, as sysadmins, need to do on an almost continual basis. However, there are several problems with some existing pastebin implementations:

• lack of command-line integration
• no version control
• no privacy settings

I recently came across a new (to me, anyway) alternative to the traditional pastebin: github gists. The following is a description of how gists work and how they differ from traditional pastebin clippings. I'll also describe some ways you can collaboratively edit gists with one or more people.

What's