[Gentoo] Save yourself time: document what you do

I was reading an article on the Bacula development philosophy, which is interesting for a number of reasons, and I saw this:

Kern: Thanks for the compliments. I am responsible for the documentation, and generally spend at least 20 percent of my time on documentation.

Nathan: What advice would you give to other open source software projects about how to generate and maintain good documentation?

Kern: If you want people to use your software, and if you don’t want to spend all your time on repeating the same support responses, you need to write lots of clear, detailed documentation. When I respond to a support request or a problem, I often put the response into the manual, or I update the manual to include the problem. Documentation is not a task to be left to the end of the project or just before the release. It is an ongoing “project” in itself–at least that is my view of it.

Nathan: This is an interesting take on the role of documentation. In addition to being helpful to the user, it also helps the developer spend more time developing and less time dealing with usage questions.

[Gentoo] IBM’s blog policy

As a followup to my post on Sun’s policy, here’s IBM’s. The collaborative creation of this policy is worth noting. It also links to the policies of Sun, Microsoft and Groove. Here’s a few sections worth stealing. =)

The core principles — written by IBM bloggers over a period of ten days using an internal wiki — are designed to guide IBMers as they figure out what they’re going to blog about so they don’t end up like certain notable ex-employees of certain notable other companies.

If your blog is hosted on an IBM owned property, avoid these topics and focus on subjects that are business-related …. Further, blogs hosted outside of IBM’s protected Intranet environment must never be used for internal communications among fellow employees. It is fine for IBMers to disagree, but please don’t use your external blog to air your differences in an inappropriate manner.

Though not directly business-related, background information you choose to share about yourself, such as information about your family or personal interests, may be useful in helping establish a relationship between you and your readers, but it is entirely your choice whether to share this information.

[Gentoo] People live on a planet

I was reading Sun’s blog policy, and I found an interesting paragraph that’s quite relevant to Gentoo’s rather more restrictive policy.

Another way to be interesting is to expose your personality; almost all of the successful bloggers write about themselves, about families or movies or books or games; or they post pictures. People like to know what kind of a person is writing what they’re reading. Once again, balance is called for; a blog is a public place and you should try to avoid embarrassing your readers or the company.

In other words, people as multi-dimensional objects are more interesting.