Open Source documentation

Open source technology is usually software but there is a growing range of open source hardware projects and a faster growing range of open source cooperative data and information Web sites. All go through growing pains. Some are developing to be better or more useful while others are on a downward slide. Here are things to look for and avoid when using or building an open source project.

Thought police

Thought police infect some projects. They tell contributors the contributions are wrong and then they tell the contributors the contributors are things the wrong thoughts. Thought police are destructive.

Some examples. One from a software project based on PHP. In PHP you can write the clauses in an if statement in two ways. The first, $a == 1 and $b == 2, is the easiest to read, easiest to teach, and easiest to maintain. The second, $a == 1 && $b == 2, is meaningless to most people and creates errors when copied as an example onto different media, including Web pages. There was a discussion running about some PHP code. A though police person barged in and told one of the code authors that the author was wrong for using and, that the author should learn PHP and use &&. Clearly the thought police person knows very little about PHP, less than the code author. The thought police person actively discouraged contributions of code to the project by incorrectly criticising good code.

Thought police are the same as bullies in the school yard. if you have ever been the victim of a girl or boy bullying you, you know how discouraging it can be. If you were not the direct victim but were in the area, you know how strong the effect can be to discourage other people from trying. One thought police person posting a stupid criticism might not stop the exisitng contributor but they might discourage 50 potential contributors who decide to not start contributing because of potential criticism.

Politically correct police

The PC police are active. They often do not openly criticise contributors. Instead they simply change content to fit the PC stereotype promoted by the PC police person.

Your open content is slowly poisoned by the PC police. They change whatever you say to whatever they want said. They may not notice the difference. They may be too ignorant to understand the difference between what you write and what they change it to. I found another example today.

Months ago I contributed a page of documentation to an open source project. The page compared two alternatives. Someone is now proposing to split the comparison into two independent documentation pages where it will be difficult to compare the options plus future updates to one page are unlikely to be applied to the other page. Comparison pages appear to be acceptable if they have many items listed in a table. A comparison page appears to be not acceptable if it is presented in a tutorial style with the options compared at decision points of the installation process.

One Web site claims to be global and lists many American people who are unknown outside of America but rejects anyone from outside of America who does not appear in the American news media and who does not pay a marketing organisation to insert fake community contributions.

One Web site claims to be open then rejects community contributions that to not conform to a narrow format that appears to be used only in some academic circles.

One Web site claims to be inclusive and accepts contributions only if they have references to legitimate Web content. The PC police on the site reject anything that is not from one of their preferred Web sites. The PC police prevent the site from being inclusive by not including references to relevant Web sites.

Swamp creatures

Some marketing people and busy bodies swamp some forums with junk. The forums then become useless without intense moderation. If a Web site does not have the moderators, the site might turn to automated moderation and create as many problems as they solve.

The swamp creates repeatedly post similar items across many forum topics and often without considering the relevance. Sometimes it is just lack of attention. You can have one post where the original post says I am an expert, I tried everything, and it still does not work.. The swamper dives in with a quick reply showing off the swamper's knowledge by using lots of technical terms and abbreviations. A separate post starts with I am a beginner and do not understand the terminology. Can someone please explain.... The swamper dives in with the same reply used for the expert. The beginner asks repeatedly for explanations of terms but the swamper defines every term by using lots of other terms. Eventually the beginner drowns in terminology, goes away, and never comes back.