Month: May 2010

Please Document the Shop: On the importance of good systems documentation

We have all heard this: You need to document the computer infrastructure. You never know when you might be “hit by a bus”. We hear this and think many frightening things, reassure ourselves that it will never happen and then put the request on the back burner. In this article I will expand on the phrase “hit by a bus” and then look at the consequences.

Things do happen to prevent people from coming into work. The boss calls home. Talks to the wife and makes the sad discovery that Mike wont be coming in anymore. He passed away last night in bed. People get sudden illnesses that disable them. Car accidents happen.

More often than these tragedies occur, thank goodness, business conditions change without warning. In reorganizations whole departments disappear, computer rooms are consolidated and moved, companies are bought and whole workforces replaced. I have had the unhappy experience of living through some of this.

Some organizations have highly transient workforces because of the environment that they operate in. Companies located near universities benefit from an influx of eager young, upwardly mobile university graduates. These workers are eager to gain experience but soon find higher paying jobs in the “real world” further away from campus. These companies have real turnover problems. People are moving up so quickly, they don’t have time to write things down.

Even when you keep people in place and maintain a fairly stable environment, people discover that what they have documented in their heads can just fade away. This is getting to be more and more of an issue. Networks and servers and other such infrastructure functions have been around for 20 years in many organizations. Fred the maintainer retired five years ago. Fred the maintainer was transferred to sales. The longer systems are around, the more things can happen to Fred. Fred might be right where he was 20 years ago. He just can’t remember what he did.

What does all this mean? What are the consequences of losing organizational knowledge in a computer organization? To be blunt, it creates a hideous environment for your computer people. The system is a black box to them. They are paralyzed. They are rightfully afraid. Every small move they make can bring down the system in ways they cannot predict. Newcomers take much longer to train. Old-timers learn to survive by looking busy while doing nothing. The politics of the shop and the whole company is made bloody by the various interpretations of the folklore of the black box. He/she who waves their arms hardest rules the day. This is no way for your people to live.

This is no way for the computer infrastructure to live as well. While the games are played the infrastructure evolves more slowly and slowly. Before long the infrastructure is frozen. Nobody dares to touch it. The only way to fix it is to completely replace it at considerable expense. In elaborate infrastructures this is easier said than done. The productive lifetime of the platform is shortened. It was not allowed to grow and evolve to lengthen its lifetime. Think of the Hubble Telescope without all the repairs and enhancements over the years. It would have burned out in re-entry long ago.

Having made my case, I ask again; for your own good, please document the shop. Make these documents public and make them accurate. Record what actually is rather than what you wish it to be. It is better to be a little embarrassed for a short while than to be mislead later on. Update the documentation when changes occur. An out of date document can be as bad as no document at all. Make an effort to record facts. At the same time don’t leave out general philosophies that guided the design and other qualitative information because it helps your successors interpret the facts when ambiguities occur.

Think of what you leave behind. Persuade your boss to make this a priority as well. Hopefully the people at your next workplace will do the same.

Posted by Laird Hariu in Eternally Regenerative Software Administration, Security, Systems Management, 0 comments

Organizations Learning to Contribute to FOSS “The Right Way”

A couple weeks ago I wrote that I would be attending the 4th Annual Linux Foundation Collaboration Summit. I wrote about much of my experience there and at the Open Source Business Conference back in March over in my personal blog: “Lessons from Open Source Business Conference and the Linux Foundation Collaboration Summit”.

However, I also wanted to make a post here to cycle back to some of what I learned from the Collaboration Summit in relation to my March 30th post about contributing, “How and why contributing to FOSS can benefit your organization”. In this post I discussed using community tools, getting involved in the community and what steps you could take to get there. This was based upon several years of my own involvement in the FOSS (Free/Open Source Software) community directly and now my experience working for a company which makes FOSS contributions.

The talks at the Collaboration Summit strengthened my resolve in and increased the clarity of my understanding about the right way of going about contributing to FOSS as a company. At this conference there were multiple talks from major companies and figures within the FOSS business world which drove home the need for working with the community. All of these companies had stories about how they had tried to contribute to FOSS and struggled because they went about contributing as a walled off company rather than contributing just like other contributors did and using the same tools that contributors did.

A keynote which really stood out and succinctly discussed all of this was Dan Frye‘s talk, “10+ Years of Linux at IBM” (video). The first half of the keynote discusses the progress of Linux within IBM, but then he moves into discussing contributing itself. Some of their take-aways were that they needed to get involved directly with small contributions and do away with closed-door meetings and canned corporate responses, IBM employees were empowered to become community members. They needed to learn to collaborate with the community to develop higher quality solutions than they could have in-house, and to start these discussions with the community early in the brainstorming process. Related to collaboration, he also discusses control, and how a company does not have it within a community and needs to learn to deal with that, instead what a company should strive for is influence within a project to help guide direction and priorities. He also suggests never creating a project. Instead he encourages companies to join a project that’s close to what they need and work with them to take it in a direction that can benefit everyone and reach their goals and scratch their itches.

What struck me most at the conference regarding the subject of contributing is they are all reaching the same conclusions about the proper ways to successfully contribute. In the end, they learned that they must fully collaborate openly throughout development with the open source communities they’re working with.

Posted by Elizabeth Krumbach in Conference, FOSS Community, 0 comments