Documenting Open Source Software

I love reading different community perceptions of both FLOSS Manuals, where we write open docs for open software. I’m also lurking on mailing lists and forums where open source projects are figuring out documentation needs for their users. Forgive me if I ramble a bit, but I’ve been thinking about these concepts lately while discussing them with other writers.

Attention on FLOSS Manuals

Here is a great quote from a recent outburst of articles and blog entries mentioning FLOSS Manuals. On the Linux and Open Source blog on ZDNet, Dana Blankenhorn summarizes his post explaining “Why open source documentation lags” by saying,

If programming is like bicycling, documentation is more like basketball. The best players don’t always win.

He offers great explanations for the lags in documentation, and let me tell you, the reasons are not just tied to open source software, all software documentation could use more team sport and collaboration efforts to create decent documentation.

On Network World in a post titled “Creating a library of FLOSS Manuals,” Amy Vernon asks, “…why do so few applications have manuals to start with?” Her initial answer is tied into the use of manuals, asking her readers, “When’s the last time you read a user manual?” Fortunately, she found the offerings on FLOSS Manuals to be quite useful. And I think that’s the key to software documentation, whether it’s open or closed, the usefulness of the doc no matter what form it takes will be its final measure (such as, distance to be tossed or microseconds spent on the page).

What’s Free and Open Software?

At the STC Summit someone asked me quite earnestly, “But what is FLOSS? What does Free, Libre, Open Source Software mean?” I think she wanted to know, is it a philosophy, a concept, a rubric, a religion? I believe the explanation she sought is available in a question and answer set on the FLOSS Manual’s About page, describing both free and open.

Open Source emphasizes availability of source code to software users. … Free Software emphasizes the freedom to modify and reuse software, which of course also requires that source code be readily available.

I wish I could pull these great quotes out of my back pocket when speaking about FLOSS, but I keep learning myself and integrating the definition more fully in my own mind.

Talking Even More about FLOSS and Docs

Last week I talked to Michael Cote last week about wikis, open source documentation, and so on, for his new “make all” podcast. See Coté’s People Over Process » Beyond Documentation – make all #004. I immediately jumped to “who are you writing for?” as the very first question to ask. I think you also should ask, “What are they reading already?” Audience analysis is important everywhere but even more so in open source I would say, because much documentation effort is focused on the developer, which sometimes means non-technical end users get ignored. Also, there is so much free, liberated content in open source, you have to visit (ans answer!) the question, do we make it or gather it.

I also said that FAQs are a perfectly good starting point, especially if customer support is your main goal. In an email exchange later, we talked about how documentation is a great conversion tool for website visitors. With web analytics, that measurement is possible. In essence, your documentation can be your storefront. Aaron Fulkerson describes it well on the MindTouch Blog, in “Your Most Valuable Storefront.”

5 Comments

  • Jim Campbell
    May 25, 2010 - 12:44 am | Permalink

    Hi Anne, thanks for the write-up about open-source documentation. It is neat to see the perspective of someone who is involved in Tech Comm in general, but not as much on the open source side.

    You mentioned Floss Manuals, but I thought I would mention a few other documentation / user assistance efforts that I find interesting these days. Here is a quick rundown of some of them.
    – Mozilla Sumo, the support website for Mozilla projects. http://support.mozilla.com/en-US/ and https://wiki.mozilla.org/Support:Sumodev
    – The Mallard documentation syntax (currently being used on documentation for the Gnome desktop help): http://projectmallard.org/
    – The Gnome documentation project: http://live.gnome.org/DocumentationProject
    – The Drupal documentation team: http://groups.drupal.org/documentation-team

    These are just a few of the projects – there are more out there! As I said, though, these are just the ones that I find most interesting to me right now.

    With regards to the question, “What is FLOSS, anyway?” I think you answered it pretty well. : ) Thanks for getting your rambling thoughts out on this topic. : )

  • Pingback:   Weekly links roundup by Communications from DMN

  • ekta
    November 5, 2012 - 12:38 pm | Permalink

    hi….I am a new learner of FLOSS….I wanted to know about weather the developers of open source software follow the same SDLC approach….where after every step we get some end product or document?please reply me

  • November 5, 2012 - 12:58 pm | Permalink

    No, for each open source project there are different methods for completing the documentation. One interesting paper on the subject studied many different FLOSS projects and their documentation processes. See https://dl.acm.org/citation.cfm?id=1882312, Creating and evolving developer documentation: understanding the decisions of open source contributors.

  • Simon
    December 22, 2012 - 7:29 am | Permalink

    I am a technical translator in mainland China and I have been following your blog for a while. Also I am keeping a keen eye on open source projects such as Drupal because I have been considering participating in these projects to jumpstart into technical writing as a career. Are there any suggestions you can make about how to participate and how to grow? Thanks.

  • Leave a Reply