Supporting Free Software – Documentation
In my day job I am a Project Manager, and one of the things I constantly try to get is good documentation. I hope I have even produced a little of it myself. But there is no topic on which I get more resistance than on creating good documentation. No one ever has time to create it, but somehow they find the resources to pay the price when they don’t have it. If getting good documentation is hard in the corporate world, how about in the Free Software world? It is equally difficult. I can’t tell you how many times I have tried to access the Help system for one of my KDE applications only to get an error that says there is no Help material available. You really feel sometimes like you are being told “We wrote it, now you figure out what to do with it.” And part of the reason is that we don’t always think about it properly (in my opinion).
I would start by distinguishing between two kinds of documentation: technical, and end-user. Technical documentation, as the name implies, is the sort of thing that the developers could provide if they chose to do so. This could get to the very deepest level of code documentation, but even if it lives at a somewhat higher level, it is not end-user documentation. And the question of whether it even exists remains. Developers like developing, but they generally don’t like documenting. And in Free Software many of these people are volunteers.
But the topic of end-user documentation takes us in a different direction, and one where people with the right skills can be very helpful. It can also be little frustrating. I recall one experience I had where I offered to help create end-user documentation for an application. When I asked to see what they had, the response was “We don’t have anything, that is what we want you to do.” Now i like to think I am a good writer, and I know I have been praised at work for the documentation I have written, but any writer needs something to start with. At work, I can make the technical people sit down with me, answer my questions, and so on. And you really need something like that to do good documentation. Good technical documentation can get you started, but to do good end-user documentation you will need to have some kind of access to the developers. And if the folks on the project you want to help don’t understand this, you need to explain it to them. They may want someone to come along and just magically make something happen without anyone else on the project being involved, but that is just not feasible. Good documentation is a group effort, really.
In writing for the end-user, you need to be able to think a little differently. End-users are, by-and-large, not technical. There can be exceptions to this rule, but this is a good starting place for writing the most useful documentation. And the best way to do this by thinking of “stories”. The Agile community tends to do a good job of this in terms of software development, but you need to carry this into documentation as well. You could write a book on this topic, and I don’t have that kind of space here so I will be somewhat more brief. Stories in this context means picturing a typical user of some kind, and imagining how they might try to use the software. Who is this person? Be specific – give this person a name, an age, a sex, a background. The better you do this the better able you will be to get into this person’s skin and see things the way they do. Then look at some questions they might have.
- Why would I want to use this software?
- What do I hope to accomplish here?
- Would I use this infrequently, or daily?
- Would I use this alone, or with other software?
And that is just a few of the questions you might want to ask at the beginning. By answering them, you set a direction for what you want to do. And if you can begin here and you can write out answers that end-users can make sense of, you can make an invaluable contribution to Free Software.
One last note is about translating documentation. Free software is in international in scope, and often the people who need it most also need it in their own language. If you can translate the documentation that is also a much-needed contribution. Many projects are looking for help with this aspect of the documentation. Just offer to help.
Supporting Free Software – Bug Hunting
In a previous post I mentioned that Free Software should more properly be considered “Community-Supported” software, and I said I would come back to discuss just what that means.
There are lots of ways for someone to support Free Software, but one of the most important is by submitting bugs to the developers. Remember that these fine people are creating wonderful software with minimal budgets, and that means they cannot possibly test their software under all possible conditions. Many of us (myself included) build our own computers out of parts we mix and match, everyone installs their own custom blend of software, etc. Under the circumstances, you have to expect that we will stumble over problems that no one knew about. And the only way they can get fixed and the software improved for everyone is by filing bugs. This is how the developers get informed about the problems, and is step one to fixing them.
The first place to look for filing bugs is with your distro. The major distros tend to have online bug-tracking mechanisms of some kind, and they will have specific directions on how to file a bug. They may decide that it should go upstream (i.e. the bug is in a package that they included but don’t directly support), but it is really never wrong to start with the distro. If you want to read more about this, a good place to start is at LinuxCareeer.com. Note how they start off their discussion:
Linux distributions and Open Source software in general are, before anything, community efforts. Every distribution lists somewhere on its’ website ways to contribute and help to the effort. And it’s quite an effort too, which programmers provide for free, working in their spare time. One recurrent theme on each of those “how to contribute” documents is “Submit bugs when found” although the exact wording may differ.
This site give more specific instructions for Ubuntu, Mint, Fedora, Debian, and openSUSE. But if you use some other distro, just go to the site of the distro and you will be certain to find how they do it. Or Google for the name of the distro and the phrase “filing bugs” and you will probably get there right away.
Now, aside from the specific mechanics of submitting a bug for your distro, there are some general things that are important to any good bug report, and you should learn to look for these:
- Did anything just change? Did you just add a new video card. for instance? If you change to a different video card, does that affect the problem? Did you just install new software? Did you just update something? Can you roll back the change and try again? Knowing the answers to these questions can be very important in determining where the problem lies.
- What were you doing when the problem occurred? Is it reproducible, i.e. if you do the same things again do you get the exact same problem? Again, a very important piece of information for tracking down the bug.
- Do you have any log data to add to the report? Get to know where this data lives, and how to access it. For instance, dmesg is a great source of information. Just including this file in your bug report can be useful, but even better is finding out how to pull out the relevant details first.
- Check to see if this bug has already been submitted. If so, you may be able to add on to the report as an additional case of the bug. Even better, if you learned how to get good information, you can improve the original bug report to the point where the developers can actually work on it. When you look at how bugs are submitted, a large number of them cannot be worked on because there is no useful information. Learn to make yours useful. Also, you may discover that the bug has already been fixed, and all you need to do is update your software. That is pretty good, right?
Here is an example of one problem I had. The software package in question was Miro, which downloads and plays videos from the Web, which for me is mostly video podcasts. And I use it every day, so this problem mattered to me. I had just upgraded my Distro to the newest version, and suddenly Miro would not play any of my videos. I checked and I could play them in other software, but I wanted Miro to work for me again. I also checked on another computer with the same Distro version, and had the exact same problem. So I filed a bug in two places, one with the distro, the other with Miro itself. I got a reply from a developer on the Miro project within hours, and he said that he had tried that exact Distro version and had no problems. So there was probably some combination of software that I tended to use that did something unexpected. He asked me to grab a log file from Miro, and send it to him. I did so, and again he wrote back promptly pointing out a couple of lines in the log file, and saying that it looked like I was missing a critical package. I checked, and it looked like this package was on my system, but I removed it, reinstalled it, and then Miro worked properly again. I think this counts as a very good outcome.
When you create good bug reports, you help yourself and you help others. And that is a big part of what it means to have Community-Supported Software.
The openSUSE adventure: Installing Packages
Well, I learned some more today in trying to install the software I use all of the time. As a long-time Kubuntu user I was used to how they set up their repositories, I know all of the command-line tricks for using apt, and none of that is any use to me now.:) But I knew that would be the case, so I persevered.
The first thing I learned is that there are a lot of repositories. I was trying to install a password manager I like, KeePassX, and finding which repository it was in took forever. openSUSE has these repositories called BuildService, and there are a bunch of them. As it happened none of them had what I wanted. Then I found one called Packman, but that didn’t have it either. Finally I added opensuse-contrib, and that had what I wanted. So now I have about 20 repositories configured. I can’t tell whether that is a huge mistake. I did notice that for some reason every repository has a GPG key that is untrusted.
Then I had one piece of software that had to be compiled. Again, everything is different. Instead of a package with everything included, you have to install the components, like gcc and make, separately. Or at least that is what got me going. If you know better, please share the knowledge.
My one big unsolved problem from today is that my favorite Chrome extension, G+me for Google Plus, is not working. I have installed it, removed it, reinstalled it, and it just isn’t working. At this point I have to call it a day, but I will try to get it going again. All of my other Firefox and Chrome extensions/add-ons seem to work fine. So, the day is mostly a success, but a few things to work on yet.
Calling All 2011 Ohio LinuxFest Attendees!
We would really like to gather a teeny little bit of information about what you liked. I promise this can’t take more than a couple of minutes : http://bit.ly/uB9D9B
And to make it worth your while, we will select one respondent at random to get a free Professional pass to the 2012 event, which gets you: A day of training with the OLF Institute, which includes lunch on Friday, a t-shirt, and admission to the main OLF conference on Saturday. These normally run $350, so it is a valuable prize.
So go to http://bit.ly/uB9D9B and fill out the survey.
And thanks from all of us at OLF.
OpenSuse 12.1
Well, I just installed OpenSuse 12.1 on one of my computers. Another one of my New Year’s resolutions was to try some other distros. I picked OpenSuse because it is a KDE distro, and I definitely prefer KDE. I am hoping to find that RPM is better than it used to be. So far, YAST looks pretty good to me. I used it to install Samba and connect the computer to the rest of my network, and it was really easy to do, in fact I thought it was easier than in Kubuntu, which has been my distro for the last 5 years.
I figured out how to add a repository, KDE:Extras, and I installed a plasmoid I really like, Veromix. But I cannot figure out how to get it onto a panel. I really like this particular plasmoid, so if anyone can explain this I would appreciate it. I tried installing it directly on the panel using Add Widget, but that errored out on me, hence my attempt to add the repository and get it that way.
I know I will stumble over how to do things in this new distro, but I am going to keep with it for at least a few months and give it a fair chance. It is time to learn some new things.
Freedom is Never Free
The words we use to describe what we do can matter a lot in how we in the FOSS community think about what we do. Once upon a time there was Free Software, as defined by Richard Stallman in the famous Four Freedoms:
- The freedom to run the program, for any purpose (freedom 0).
- The freedom to study how the program works, and change it so it does your computing as you wish (freedom 1). Access to the source code is a precondition for this.
- The freedom to redistribute copies so you can help your neighbor (freedom 2).
- The freedom to distribute copies of your modified versions to others (freedom 3). By doing this you can give the whole community a chance to benefit from your changes. Access to the source code is a precondition for this.
Now, I happen to be a big supporter of this. I love the idea of Free Software. And I have noticed that some people I greatly respect, such as Jon ‘maddog’ Hall, are always careful to refer to it as Free Software. Nonetheless, there are problems with this terminology. If you have been around FOSS for very long you have noticed that the word “free” admits of several meanings, one of which has to with the cost. And that was never the point in FOSS. There is nothing in the definition of FOSS or in the GPL that says you are prohibited from charging for your software. And because of the ambiguity in “free” we have to be careful to use “Free As In Freedom” to denote what Stallman meant by the Four Freedoms, as distinct from “Free As In Beer” to denote lack of a monetary price.
A later term was developed called Open Source, which put the focus on making the source code freely available. Now, it is clear from the Four Freedoms above that this is essential to Free Software, so I am not sure just how big a difference this makes. But if you want to explain to the average user why any of this matters, you have to acknowledge that the average user really doesn’t care if the source code is available since they can never imagine themselves trying to modify the code. In point of fact, I would expect that it is highly likely that I will go to my grave without ever attempting to modify the code of any software I use. I am not a programmer, and I don’t have any desire to be one. I like programmers, some of my best friends are programmers, and the world is undoubtedly a better place because of programmers, but I don’t think that is my role in FOSS. So I don’t have strong interest in looking at the source code. And to you in the back with your hand up, I agree that it would be silly to buy a car that had the hood welded shut, but I don’t repair my own cars either. Instead I support the economy by helping a mechanic to earn a semi-honest living.
The term I have adopted for this purpose is to call what we do “Community-Supported Software” because I think that puts the emphasis where it more properly belongs, at least for some uses. If we value this software, I think we all have a responsibility to support it in whatever way we can. Some do that as programmers, but the rest of us have a role to play. And I want to explore some of those options (and maybe motivate some people to get involved) in some posts over the next few weeks. And if you find this discussion at all useful, please feel free to forward to anyone you think will be interested. Because I think it is true that freedom is never free. It requires all of us to take part in defending and supporting it.
It’s Just Semantics
Yesterday I began my morning with a meeting involving members of various departments who are dealing with a major change to our IT systems. We are replacing a system from Vendor A with another from Vendor B, and just about everything changes. As a result, we have a lot of meetings. But I didn’t bring this up to get sympathy. Everyone has pain in their lives, and mine is not particularly more impressive than yours.
But in yesterday’s meeting, we got to to a discussion of terminology. You see, Vendor B sold us a system that uses different names for a wide number of of our data fields, and we needed to agree on the names we would use in our reporting systems. Should we use the new vendor’s names, use the ones we had traditionally used, or some combination of the two? Now, at this point I’m sure you’re thinking “Gosh, that sounds like fun.
I wish I could have been in that meeting!”
But what got me thinking was when one of the IT folks said “That is just semantics. I don’t care what you call them.” This statement was so profoundly wrong that I nearly admired it for the awesome scope of its wrongness. The first level of wrongness comes when you consider that all of us at this particular site, in all of the different departments, need to talk to each other. And that means we all need to understand what we are talking about. I wondered if this IT person had ever heard the term “naming convention”, and if so, did he comprehend why that was important.
Then I got to thinking about that phrase “It’s just semantics.” This is where the real problem lies, I realized. It is a common phrase, and usually used to imply that the meaning of the words is not important to understanding the issues at stake. In this colloquial sense it says that people sometimes use weasel words to avoid a truth. For example, a politician trying to explain away an embarrassing situation, like Clinton saying “I did not have sex with that woman.” We correctly see that people who do this are misusing language to confuse the situation.
But saying that this is semantics is profoundly wrong. What is really happening when people use this phrase is that they are saying that words and their meanings do not matter. And when you go down that road you have a serious problem. I doubt you can even think intelligently if you cannot use words with a certain degree of precision. And communication becomes pretty much impossible if we cannot use words and agree what we mean by them. That is what semantics is really about. So if someone accuses me of using semantics, I thank them for the complement. What they have said is that I care about what I say and try to use the best words to convey the meaning I have in mind. Of course, they don’t realize that is what they said.
Trent Reznor on Social
This courtesy of the current issue of Wired magazine: “I don’t care what my friends are listening to. Because I’m cooler than they are.”
So, can I claim that is why I’m not interested in social recommendations for music?
Android, Apple, and Market Dynamics
Or Why Tim Cook may be the world’s unluckiest man
Please understand that I don’t wish anything bad to Tim Cook. I’ve never met the man. But I am observing something about the market dynamics in the smartphone and tablet market that I have not yet seen anyone else talk about. Eric Raymond in his blog Armed and Dangerous has covered the idea of price pressures from Android affecting Apple, and I consider his blog required reading for anyone interested in this topic. But I think I can offer a slightly different take on the issue.
If we start with smartphones, Apple really kicked off this market, and raced to an early lead. The first iPhone was unveiled in January 2007, and there was nothing like it. This phone got 2.7% of the mobile phone market in 2007, 9.6% in 2008, and 15.1% in 2009. On November 5, 2007 the Open Handset Alliance was announced, and the very first version of Android unveiled. On September 23, 2008 the G-1 was released with Android 1.0. In 2008 this gained Android only .5% of the mobile phone market, but this increased to 4.7% in 2009. So in 2009 we have a situation where Android’s market share is less than one-third of Apple’s. Yet by November 2010 Android pulled ahead (slightly) at 26% to Apple’s 25%. And by September 2011, 10 months later, Android is at 44.8% to Apple’s 27.4%. What makes this even more significant is that these share numbers are for the U.S., and it appears that Android is even more dominant in other countries.
If we look at the timeline, it looks like Apple is first to market, and holds a lead for nearly three years before the competition catches it. I think this may be significant for the tablet market. The iPad was introduced in January 2010. In the most recent figure I could find, which is for September 2011, it looks like 75% of the market is held by iPad, and 25% by Android. I think these numbers are pretty comparable to what we saw in the smartphone market if you allow for the fact the the market share numbers were for all mobile phones. Nokia was still selling candy bar phones in 2009, for instance. If we take the smartphone market in 2009 as a two-horse race between Apple and Android, it really looks very close to 75% Apple and 25% Android then as well. I point this out because even as Android was starting to dominate sales in the smartphone market, I heard a number of people claim that the tablet market was different. But I never heard anyone give a compelling argument as to why the tablet market would be different. Maybe there will be a different outcome this time, but I’d like to hear a sane evidence-based argument before I believe it. If the pattern from the smartphone market is repeated, we could see something like a 50/50 split by the end of 2012, with Android pulling ahead to dominant position by the end of 2013.
Now at this point I have mostly recapped some numbers, but not added anything significant to Eric Raymond’s analysis. I think I can do that now by adding something based on the history of the consumer electronics market. Back in 1990 Professor Michael Porter at the Harvard Business School published a very important work called The Competitive Advantage of Nations. I used this book with some of my more advanced students because it had some great insights. Prof. Porter started with the insight that national economies are not the appropriate level of analysis, and that in specific markets a country might have an advantage while not having it in other markets. So he looked at a number of specific markets where one or another country dominated and asked why that was the case. In the market for consumer electronics, Japan was clearly dominant (remember that in 1990 Sony was still a major force, not a bumbling also-ran<g>). And why was that? Because of the intense competition within the domestic Japanese market. Japanese consumers would purchase the newest products with great fervor, and always demand newer, better products. The product cycles were a matter of months, while comparable US firms, for instance, were still operating with product cycles of years. As Prof. Porter noted, this placed huge pressure on Japanese companies, such that if they could succeed in the Japanese market they would find competition in the global market relatively “a piece of cake”. And we now know that they basically eliminated the American firms in this market and took it over.
I think this example is relevant to the smartphone and tablet markets as well. I expect that the combination of rapid innovation, short product cycles, and price pressures will create further challenges for Apple. The competition is not from Japan this time, but from the countries that learned from Japan, which would be South Korea, Taiwan, and China. This is where you find the companies like Samsung, HTC, LG, Huawei, etc. HTC, for instance, doubled its shipments of phones from the first half of 2010 to the first half of 2011, and its product cycle is in the area of 6-12 months between concept and a product in the hands of the consumer, according to its COO, Matthew Costello (The Economist, 10/8/11) . This is rapid, and it is only one company. Together, these companies represent the next wave of Asian Tigers, and they came to the top by out-competing the Japanese. Already in China, which by any measure is the biggest growth market for mobile, Samsung has a larger market share than Apple. Add in Motorola, and new entrants looking for a foothold, like Acer, and you have a lot of competition. These companies are releasing a new phone every month, and sometimes more than one. And any time a feature proves popular, it is quickly adopted by every manufacturer. As a result, the Android phones, which started playing catch-up, are now moving ahead of Apple. Already the technical specs for Android phones exceed those for Apple, and in terms of software it was notable that the latest version of iOS mostly played catch-up to Android.
One way to think about this is the contrast between Intelligent Design and Evolution. Apple is a very centralized tightly controlled ecosystem that represents the Intelligent Design side, while Android represents the Evolutionary approach. From this perspective, the fragmentation that some people complain about is not a failure, it is Android’s greatest strength. This is what lets Android move into every conceivable market segment, and is a central reason for Android having double Apple’s share in the smartphone market. And when you conceive of this as an Intelligent Design vs. Evolution competition, it is worth noting Leslie Orgel’s Second Rule: “Evolution is cleverer than you are.” Even if Apple’s designers are, pound-for-pound, better than anyone else’s designers, they can’t beat the frenzy of experimentation that comes from the Android market.
The next area worth looking at is China. This country is just starting to gear up for massive smartphone usage, and there is no doubt that large numbers of Chinese consumers appreciate the Apple products. After all, look at the many Apple stores there that are doing great business. Of course, Apple never heard of these stores until recently because they are all fakes. Still, imitation is the sincerest form of flattery. But the largest growth in the Chinese market is going to come from less expensive phones, and that is simply not in Apple’s DNA. In a Wall Street Journal article the Chinese market was analyzed and right now Samsung leads Apple slightly (15% to 13% respectively). But the really interesting development is the charge by Huawei, ZTE, and other Chinese companies to develop smartphones aimed at the price point of 1000 yuan (around $157 at the time of the article). ZTE, for instance, has an order for 2 million 0f its Blade smartphone, priced at 999 yuan, or free with a 2-year contract. And these phones run Android. Computer maker Lenovo has also jumped in with an Android phone (the A60) with a price of 959 yuan. This kind of competition at the low end will be just as challenging for Samsung as for Apple, but it represents gains for Android.
In the tablet market, I expect similar dynamic for the same reasons. Too many analysts have looked at current market share declared “Game Over”, using statements like “There is no market for tablets, there is only a market for iPads.” This completely ignores the history of smartphones, and is, I believe, fundamentally mistaken. Android already has approximately 25% of the global tablet market. And just within the past couple of days (as I write this) comes the news that Amazon has increased its orders for the Kindle Fire for the second time, up to 5 million units. And this has not even been officially released yet, so they must be getting a lot of pre-orders. So if this follow the same pattern, and I see no reason why it shouldn’t, expect rough parity between Android and iOS in the tablet space by the end of 2012, with Android pulling ahead in 2013.
To get back to the subhead of this article, all of these factors were in play when Steve Jobs was still the CEO of Apple. If he had not gotten cancer, if he was still alive and running things at Apple, everything we have talked about would have happened pretty much on schedule. In fact, the dominant market share in smartphones going to Android did happen while Steve was in charge. For now, Apple is able to generate huge profits even as its market share is eroding, but that cannot hold up indefinitely either. Electronics companies all over the world can see the importance of the mobile space and want to be there. And Android is pretty much freely available to all of them. Chines companies that focus in driving down manufacturing costs (the story goes that if you ask any Chinese manufacturer what they plan to have as a marketing advantage, they all answer “Price”) will adopt Android because it gives them a software stack free of charge. Combine this innovation with Moore’s Law, and ask yourself what happens when the equivalent of a Samsung Galaxy Nexus is free with a contract, or perhaps $150-200 outright with no contract. There is no room for Apple’s margins in that scenario. And that is why I think Tim Cook may be the unluckiest guy in the world. When these things happen, no one will say that it was due to market forces that no one could have prevented. They will say that somehow Steve Jobs would prevented it, and that Tim Cook just was not up to the job.
Ohio LinuxFest Registration is Open for Business!
The premier Linux event in the Mid-West USA will run Sept. 9 through Sept. 11 in Columbus, Ohio, and registration is now open to all. Keynoters include Cathy Malmrose, Bradley Kuhn, and Jon ‘maddog’ Hall. There is an extensive Medical track focusing on the use of Open Source in various aspects of medicine, training from the Ohio LinuxFest Institute, and a great slate of presentations. Register now and reserve your place.
As always, we have a “Enthusiast” category for those short on funds. If you pre-register at the Web site, you can join us free of charge. Walk-ins will be charged a small fee.
