Tag Archives: opensource

Open Help Conference, 2013

This weekend I attended the OpenHelp Conference in Cincinnati. Unfortunately, I was only able to go to one day of it, as we had to be back for something Sunday morning.

It was smallish, and so there was a lot of good conversation and brainstorming.

The focus was both documentation and support, which are, of course, deeply intertwingled. It gave me a lot to think about, and I really wish I could have been there for the second day as well.

Siobhan McKeown, from the WordPress documentation team, was at the conference, and took amazing notes, so I’m going to link to her writeup for each talk.

The day started with Jorge Castro talking about using StackExchange to handle the Question & Answer part of support.StackExchange is part of the StackOverflow family of sites, Each StackExchange site is focused on a particular community, and is very focused on Question and Answer format, rather than general discussion. It allows users to vote for the quality of questions and answers, and seems to be a great way to get the subject matter experts more directly involved in the support process.

Siobhan’s notes are here.

Following that, Michael Verdi, from the Firefox support team, talked about the SuMo site and the work that they had done to help users find the answers to their question. Of particular interest was some graphs he showed of the improvement in customer satisfaction, as well as the rate of answered questions, brought about by just improving the search functionality, to help users find the right docs so that they didn’t even need to ask their question.

Firefox has their own home-grown, but Open Source, solution, called Kitsune. It has some StackExchage-like features, and also has a great tool called Army of Awesome, which is a way to watch Twitter mentions of your project/product, and ensure that at least one person from the expert community has responded to each one.

Here’s Siobhan’s notes.

This was followed by a panel discussion including Jorge, Michael, Jeremy Garcia (LinuxQuestions.org, and Siko Bouterse from Wikipedia. The discussion ranged from Wikipedia author retention to further discussion of many of the issues that Michael and Jorge had raised.

I spoke next, talking about listening to your audience. This is something I’ve thought a lot about over the years. My trepidation in speaking at this conference was that it seems like many of the people there know a lot more about documentation and support than I do, as I’m largely self-taught in this area. But it seemed that my remarks were well received. Once again here’s Siobhan’s notes, which in this case are way better than my own notes for my talk.

I was the last speaker of the day, and this was followed by a general discussion of the things that had been raised during the day, as well as many related issues.

You can see a lot of commentary about the events of the day, and of Sunday, by looking at the #openhelp keyword on Twitter. I’m looking forward to reading Siobhan’s notes from Sunday’s sessions.

Chores

Disclaimer: I don’t require, or even particularly care about, your approval of my parenting style. I will cheerfully ignore any parenting advice you offer. Unless you’re my parents.

My kids are very goal-driven. My son wants to save for a new iPod. My daughter wants a particular pair of shoes. These things motivate them.

But when it comes to something as pointless as taking out the garbage or vacuuming the living room, it’s hard to get them to see the point. They’ll do it when told, but they’re not likely to think of it on their own.

We’ve gone through a number of experiments in getting them motivated to do their chores, including tying what chores they do to how much allowance they get. But that’s a huge hassle to keep track of.

Last week I decided that since I like hacking on Open Source anyway, I’d throw something together to both track what chores they’re doing – so that it’s less work for us – and also to provide them with some incentive.

So, here it is: Chores is a PHP/MySQL web app to track what chores they’re doing, and tie their allowance directly to that. I chose PHP because it’s easy and, more importantly, I thought it might lower the bar to getting other folks to pitch in, whereas mod_perl or mod_lua might make it certain that I’d never get any help.

Chores is currently very simple, allowing you to:

  • Manage user accounts, and define how much money a point is worth for those individuals, so that each person can have a different base allowance.
  • Manage chores, and define how many points each chore is worth, and how frequently it may be done.
  • Track when a chore has been done, who did it, and when it can be done again.
  • Tell you how much you have earned today, and so far this week.
  • Provide reports of allowance earned for any given time period.
  • Formats nicely on the iPhone, iPod, and Nexus7, so that the kids can use it from whatever mobile device they have in their hands at the time.

Chores

I have other stuff planned, but for the moment we’re kind of in a testing phase, to see if this actually works to motivate them.

I don’t yet have a packaged distribution, because I don’t have any documentation written, other than very rudimentary install docs. But you can check it out of svn if you want a copy. Patches are eagerly accepted, and if you’d like to participate on the project I’d be glad to add you to it.

SourceForge Allura submitted to the Apache Incubator!

Today we submitted Allura to be considered for the Apache Software Foundation Incubator program.

Allura is the software that powers SourceForge’s developer experience. It offers source code hosting, discussion forums, issue ticket tracking, wiki, mailing lists, and much more. It’s been Open Source from day one under the Apache License, and we’ve decided that we want so much more.

By submitting Allura to the Apache Incubator, we hope to draw an even wider community of developers who can advance the feature set and tailor the framework to their needs. With the flexibility and extensibility Allura allows, developers are free to use any number of the popular source code management tools, including: Git, SVN, or Mercurial. We are indeed willing to turn our own open source platform in a tool that everyone can use and extend, and we believe Apache is the best place to steward the process.

The Apache Software Foundation is a non-profit that provides the legal and technical environment for Open Source projects to flourish. The Incubator is the mechanism for accepting new projects into the foundation. Today we’ve submitted our proposal to the Incubator, and over the coming weeks and months, will continue building a larger community around Allura.

We’re very excited about this step and think that it’s going to be a big turning point in the history of SourceForge. Many of us are thrilled because we have been huge Apache fans for more than a decade, and have been actively working to support the Apache OpenOffice podling. We look forward to collaborating with some of the brightest people in the world, and benefiting the thousands of Open Source projects that are hosted at SourceForge. It’s clearly the best of all possible worlds.

You can read more about Allura features, and you can read more about the Apache Incubator. We hope to be joining a truly stellar group of projects in the Incubator.

If you want to participate in the Allura development, there are many ways for you to get involved. There’s the source code, documentation, UI/UX, and just using it and telling us what you like or don’t like. We’d love to have you as part of the Allura development community.

Be careful what you start

I’ve committed a few patches over the last few weeks from a possible new contributor to the Apache HTTP Server documentation effort. Today I warned him that if he keeps it up, there’s a chance that someone will propose that he be given commit access, and you never know where that can lead.

It reminded me of a day just a short time ago (ok, 12 years … ) when someone committed a few initial patches from me. And look where it took me.

“It’s a dangerous business, Frodo, going out your door. You step onto the road, and if you don’t keep your feet, there’s no knowing where you might be swept off to.”

Joshua Slive

In September of 2000, I made my first commit to the Apache HTTP Server documentation. To be exact, it was on September 12th.

On September 8th, four days earlier, Joshua Slive made his first commit, and from that point went on to completely change the way that we did documentation. We had been editing HTML files. He converted everything to XML, and built a transformation process to convert them to XHTML, as well as a variety of other formats. This made the documentation more useful, but also much easier to write. And it made the translation process much easier. (No, it certainly wasn’t only Joshua that did this, but he took the helm at this time and made it happen, with the help of many others.)

Then, when he went to grad school, Joshua stopped being quite so active. His last commit was on March 12, 2008, nearly four years ago.

I mention all of this today because last night, according to Ohloh, four years to the week after Joshua stopped committing, I *finally* passed him, in total commits.

ohloh

Joshua, thanks for the work that you did. Any time you want to come back and pick up where you left off, we’d be delighted to have you.

Moving Furniture

I work from home, and our house is not enormous. When I first started working at home, we put a desk into our bedroom, and got a shoji screen to partition the room into two rooms. It’s worked pretty well, but there are some drawbacks to the room layout. The room felt rather cramped, and because the desk was just a couple of inches too tall, we could no longer open the window any more.

I’ve been working that way for a little over two years now, and a few days ago we decided to try to rearrange.

The trouble is, with a lot of bulky furniture, and not much maneuvering space, it’s not something you really want to experiment with.

Open Source to the rescue. We downloaded Sweet Home 3D, from SourceForge, measured all of the furniture in the room, and then started moving it around.

Sweet Home 3D has a library of furniture items that you can resize to exactly the right dimensions. You put the outlets on the wall, as well as the pictures, so that you can see whether furniture will block outlets, and whether you’re going to have to rehang any of the paintings. You can position things in three dimensions, so you can set lamps on top of tables, or stack crates, and you can see all of this in a 3D model so you know what it’s going to look like.

rearranged_room
Rather than spending a few hours hurting our backs, we were able to position things exactly as we want them, and plan out how we were going to get things there with the minimal amount of effort.

So, my desk is no longer by the window. (Yes, I could see the squirrels, and they were, indeed, merry.) but also the room feels much more open, and we’re not always dodging one another when we walk around the room. The lighting is better, and best of all, I don’t hurt all over from having to move the furniture two or three times to get it right.

In addition to the built-in objects, Sweet Home has a community website where people can contribute their creations. I imported an office chair from the website, because the one that was built in didn’t look right. There’s also trees, cars, and people, if you want to make a model of your entire house and surrounding land.

downloadable_objects

You can even create a video walkthrough of your room by selecting places to stand, and what direction to look. The software does the rest, connecting the positions smoothly to create a view of the room.

You can see an example of this below – the desk isn’t quite right, and I couldn’t find a shoji screen, but the general layout is right.

So, over all, four thumbs up from the Bowen moving team. I start work today in my “new” office, and although there’s still a lot of stuff still to be put away, it’s nice to have it done with so easily.

IT at the University of Cincinnati

On Wednesday evening, I had the great privilege of being invited to the University of Cincinnati to attend the basketball game against Notre Dame, in the President’s box at the arena. In attendance, in addition to the President himself, were various people from, or connected with, the IT (Information Technology) program at the University of Cincinnati.

The IT program covers a broad range of computer technology related fields, and has specializations in networking, databases, programming, and various other areas. Students are exposed to a wide variety of computing platforms, so that they don’t get into a job interview situation and have to admit that they only have training on Microsoft products. Or only Linux products, for that matter. A breadth of experience is pure gold in an interview situation.

Hazem Said, the new head of that department, was my kind host at the game, and we talked about a variety of ways that Open Source can feature in an IT curriculum. I’m really excited about the kinds of things that are in the future for this program. We talked about having students participate in healthy, mature Open Source projects as part of their training. This would give them experience not only in software programming, but also in project management, cross-cultural communication, customer support, and marketing, among other things.

When I was in college – which wasn’t so very long ago – there were some computer classes, which were mostly programming, but nothing that covered the real discipline of Information Technology in the way that I saw on Wednesday. It gives me a great deal of hope for the next generation of IT professionals that come of this program, and other programs like it around the world.

By the way, if you’re ever invited to a basketball game by the head of a University department, do a little research, and don’t wear a shirt with the other team’s color. (Really, it was an honest mistake!)

Open Source and The Cloud

I had something of an epiphany in the shower this morning. I discovered that I actually agreed with Bradley Kuhn about something.

TLDR: Is “the cloud” a threat to Open Source? I stopped working on an Open Source calendaring project because of Google Calendars.

Several months ago I attended (part of) a talk by Bradley about how The Cloud (whatever that is) is a threat to Free Software. (Yes, I know what The Cloud is. Snarky remark in reference to all the different things The Cloud might mean to various people. See Simon Wardley’s wonderful talk about what the cloud is.)

His reasons struck me as so outside of my way of thinking about software that I ended up leaving the talk. Oh, also, Skippy wanted to go to lunch, and that sounded like a lot more fun. Nothing personal, Bradley. He was talking about how something like Google Calendar (actually his example was GMail, but hold on a minute) was a threat to Free Software because the code, even though it’s in Javascript and right there in front of you, can’t really be inspected (ie, you can’t learn from it) because it’s hugely obfuscated. Also, you can’t see the back end. So here’s a service you can use for “free”, but it’s not Free, because it’s in chains, metaphorically speaking.

Then, this morning, I was thinking about why people are involved in Free/Open Source software, but also why they stop being involved, and I realized something.

I used to have a web-based calendar thingy. It was written in Perl, and it was really very cool. In fact, it not only started my passion for Open Source (it was the first thing I ever had on CPAN, and it was the first software that I ever wrote which was featured in a book!) it also paid my mortgage for a few years. I used to write calendaring applications for the General Motors Desert Proving Grounds in Mesa, Arizona. Although that plant is long closed, their scheduling ran on my software. If you wanted to schedule a test on the dust track (tests a vehicles various rubber seals to make sure they keep out dust, as well as handling in those conditions) you used the web-based scheduling application, called D.U.S.T. (I forget what it stands for – Dusttrack Usage Scheduling Tool or something) and scheduled it. This worked better than grubby bits of paper, because it didn’t get lost, and you always could get to it without walking down the hallway.

Also, when I was at Databeam, back in the late 90s, I wrote a similar application for scheduling conference rooms (clever name: Conference Rooms). I went up to the front desk one day and stole the conference room scheduling book and hid it, forcing everyone to use the online scheduling app. Strangely, it worked, and I didn’t get fired.

Then, I got involved in a project called Reefknot, which was an implementation of various international calendaring standards, in Perl. That was humming along nicely. And I had a dozen different calendar modules on CPAN.

By the way, in case you don’t know, calendaring is hard. Sure, it looks easy, but then you get into things like “every other Monday at 10am, except during company vacations.” Or possibly “the last day of each month.” Think for a little while about how you’d implement that, and your brain will start to melt just a little. “every monday” suggests a simple solution, but as soon as you start having to deal with exceptions, things get very very complicated. And what with different length months and leap years … and don’t even get me started on time zones. *shudder*

Anyways, then something called Google Calendar came along. It worked with all of the various calendaring applications. It did the various calendaring specifications, including the long-elusive CalDav. We were all very excited in the calendaring community, but then an odd thing happened. People stopped working on calendaring stuff. Because, you know, it’s already done.

So, I stopped working on an Open Source project because there was an implementation in the cloud. (ie, online somewhere.)

So, was Bradley right? Did Google Calendar kill the Reefknot project specifically because it’s closed source? Yes, in a sense. I don’t believe, as the FSF does, that closed source is intrinsically immoral. But there’s a direct correlation between the projects I no longer work on, and great cloud based implementations of the same functionality, where I don’t have access to the source to participate.

Furthermore, as my interaction with software is increasingly via a browser, and not via running software on my own computer, I have less and less incentive – and ability – to tinker with those things.

Now, I’m weird, I still run several of my own servers. Granted, those servers are “in the cloud”, meaning that I have no idea where they are physically located. But I have root on them. I build software from source on them, and tinker with that source from time to time. I tinker with the source code of my blog, even though there’s a good blogging platform “in the cloud”, but I also have several blogs on Blogger, simply because it’s simple and I don’t want to monkey with it.

So, although I disagree with Bradley’s philosophically, I find that he may be completely right for more pragmatic reasons.

But at the same time, Open Source has a whole new rebirth of late, and there continue to be ever more exciting projects out there. I’m much more concerned about my kids, and what they will find to hack on. My son is a hacker. He likes to build stuff, take stuff apart, break it and fix it, figure out how it works. I don’t know if I’m doing an adequate job of encouraging this. I really need to get him a subscription to Make magazine. I wonder, however, when he gets a little older, if he’ll be interested in programming. I think he’d be really good at it, but it would be a great shame if the removal of applications to The Cloud also results in a lack of opportunities to hack on code.

Write a better FM

I’ve been delighted to see the “Write a better FM” meme that’s been spreading slowly through various blogs. I understand that I’m to attribute this to Kathy, but I’ve been saying this for years. It’s not sufficient to tell people to Read The Fine Manual, you have to actually listen to the questions that they are asking, and make sure that TFM actually answers them. And, if it doesn’t, then make it better.

This is sometimes as easy as it sounds, but usually isn’t, for reasons that are often non-obvious to people that are in a place to make the world better.

It’s too hard to make the docs better. Those of us who are involved in documentation need to:

  • make it easier for folks to tell us what’s broken
  • be less defensive when they suggest ways to fix it
  • clearly identify our audience and listen to their problems
  • provide clear, correct, efficient ways for them to achieve their goals, rather than telling them that they have the wrong goals

If we don’t, what happens is that a thousand stinkweeds bloom. I’m discovering this the hard way with mod_rewrite. Because the documentation for mod_rewrite is so intimidating, and folks don’t know how to contribute changes to it, instead they write hundreds of HowTos and tutorials and recipes and rants about how to do things in mod_rewrite. These articles are, for the most part, wrong. The ones that work, often do so by sheer chance, and are prone to break if attempted elsewhere. But desperate users take these tutorials, hack on them until they mostly work, and they pass their hard-won ignorance on to other folks.

We could have prevented this, but we chose, by our inaction, not to do so. The problem is *much* harder to fix than it would have been to prevent.

I’m thinking about better ways to allow end-users to tell us that the docs suck, or to suggest improvements. I’ve never been a fan of the PHP methodology, which I have at times called “Scripture With Commentary”, primarily because so much of the commentary is crap. However, it gets the job done, and seems to be the best of the bad. I’d love to hear your suggestions of better ways to collect user feedback, and, perhaps more importantly, incorporate it into the end product.

Writing Documentation

Someone (and I now can’t remember who – I think it was Philip Olson) pointed me to Writing Open Source this week, and I’ve been somewhat fixated on it since.

I’ve been writing technical documentation for more than a decade now. 12 years sounds about right. Let’s go with that. I’ve been told I’m good at it, so I keep doing it.

I’ll let you in on a little secret. I don’t tell just anybody this, because they think I’m a freak. I actually enjoy writing documentation. I enjoy figuring out how things work, and then writing about it so that other people don’t have to figure it out. I enjoy catching the first glimmer of the spark of understanding when someone reads what I wrote and gets it for the first time. I love it when people say “Oh! I didn’t realize it was that easy!” and “Why did it seem so complicated before?”

There are precious few places that do documentation well. There’s a number of places where Open Source documentation, and software support in general, typically falls down.

* Tell the user that they’re an idiot, and probably too dumb to use this software. This is done in a variety of ways, and is often abbreviated RTFM, but TFM is often insufficient.
* Pretend that the end-user cares about the architecture of your software. They don’t. They just want to get their job done.
* Fails to distinguish between end-user and developer documentation, and, if there is a distinction, the path from one to the other is left as an exercise to the reader
* Refuses to consider the interrelationship with related technologies, and continually tells the user that “that’s a problem with ProductB” rather than giving them the support that we’re qualified to give.

And many, many others.

As I looked at this website, I became more and more persuaded that perhaps I could help in the effort to write a guide of how to write Open Source documentation – not from the perspective of whether to use passive voice or not, but from the perspective of identifying with your audience and answering the questions that they’re actually asking, not the ones that you feel that they should be asking.

On a related note, during a recent conversation on IRC I suddenly realized that I’ve been working programming jobs all these years because I haven’t been able to find a position that’ll pay me to do what I really love – writing technical docs. I wonder where this realization will take me in coming years.