Community Building and FLOSS Manuals

FLOSS Manuals community in action.
FLOSS Manuals community in action.

In 2006 or so I started FLOSS Manuals (FM – the old www archive is here). Essentially I got back from Antarctica and wanted to give up the art world. I didn’t really know what I wanted to do but I wanted it to be a challenge. I also wanted it to be something I built from the ground up. So, I imagined that making the biggest collection of freely licensed manuals for free software would be a good challenge, and along with that a comminty of software documentors. At the time, the state of free documentation was pretty poor with individual projects generally having little or no docs (with a few exceptions).  There were also some old school approaches around, such as the Linux Documentation Project, and proprietary approaches like O’Reilly Media. I respected both but wanted to see free quality manuals out there.



FLOSS Manuals icons.
FLOSS Manuals icons by Lotte Meijer.

This was actually a strange time for documentation. Books still reigned and docs were those things you did when you got time. This created very strange dynamics at times. For example, being ‘the author’ of a book about software that was published (particularly) by O’Reilly made you crown prince(ss) of that project. You were then a star. Many projects, believe it or not, saw this as the only way to make money. They saw publishing as the revenue model. The result of this was that I was often chased away from projects because there was some self-appointed guru who had not yet written the book and they didn’t want FLOSS to steal their fame and thunder. This was really frustrating. I found it particularly frustrating because  I knew that authors who were published generally made little or nothing unless the publication was a blockbuster (which was very rare).

We were patient with these projects. As the years wore on, some software producers acclimatized to the new state of docs on the web and came to be ok with FLOSS Manuals writing (much needed) docs for their projects.

I had some material I had written during a period when as an artist I led workshops about free software t (I traveled the world teaching free software, particularly those softwares related to streaming and sound).  I needed somewhere to house the material, and then I needed to build a community of contributors who would add more docs as well as improve the existing ones.

Hence I started FLOSS Manuals. The first thing I did was build the technology, as I have explained elsewhere. I then put the docs on the new platform and waited for the hordes to come. Of course, they didn’t come. Ah…. I thought, someone forgot to tell me you have to build community. So I went about promoting FLOSS Manuals. Still they didn’t come. Not one. Then I started making more docs to make the site look active. Still no one. Then I registered accounts under many aliases on the site so it looked like there were more people than me at work. Then I waited.

It took quite a while. I don’t actually remember how long, maybe 6 months or so, before I got my first ‘anonymous’ bite. Some nice chap registered on FLOSS Manuals and made some improvements to a manual on Pure Data (Pd). I remember being so crazy excited. At last! I did some homework, trying to find out who this person was. I was so excited, I wrote to them and gushed. Of course, that scared them away and I never heard from them again. Ha!

FLOSS Manuals icons in felt.
FLOSS Manuals icons in felt.

I went back to writing and promoting. Slowly, slowly, the community built up. I can’t remember that period well enough to suggest much secret sauce for the initial moments. These are the most critical moments as each little bit contributes to bringing a community to life. I remember some key characters that got in early and helped bring in others.  The wonderful Mancunian, Mick Fuzz, was one such person – he was the first guy I met that thought documentation had as much potential power as I did. That was liberating and validating for me and I was excited to meet him.

Mick Fuzz far left.
Mick Fuzz far left.

I remember Anne Gentle, a technical writer from Texas who was always looking to discover new ways to make docs. Also Andy Oram from the O’Reilly Boston office gave me lots of encouragement and promoted FM. Janet Swisher (now at Mozilla) helped spread the word a great deal too, and there were many others. These were central characters that formed the basis of a community, the fundamental roots of the organisation. I should say that most likely I didn’t find them, they found me, which speaks of the need to be out there and be seen but also, in order to be taken seriously I think you have to have something to show. A starting point that others can build on.

Andy Oram second from right.
Andy Oram second from right.

At the time I was very sold on the benevolent dictator model. I didn’t have any other models to play with really. I did have community building experience fro my time as a manager of radio in NZ, and from my time as an artist. But I wasn’t sure what I could use from past experiences.

I think I was probably a little over zealous at first. We had a common mailing list and I think I moderated it well but probably I was more focused and engaged than necessary at times.

Janet Swisher, far right.
Janet Swisher, far right.

I learned a lot quickly, however. For example, I became very good at redirecting noisy, distracting, traffic.

Several issues came up over the years that were just a sinkhole for wasting community energy. One such issue was the ongoing blahblah about licensing of the material. FLOSS Manuals required all contributors to agree to licensing under the GPL. For those that don’t know, the GPL is actually a content license, worded to look a little software-specific. Don’t trust my reading of this, but do trust me when I say I talked to many many lawyers and experts on this and they all agreed. The only people that I found that didn’t agree were those that knew little about licensing and those were, unfortunately, the people that ended up on the list. The other problem people had, was to do with the Free Documentation Licence, which is one of the most unfree and ridiculous licenses ever made. FM first used the FDL, as after all, it was made by the Free Software Foundation – the same people that brought us the GPL. So, if it comes from the FSF and has the words free documentation in it, then it must be all right, right? Wrong. As I later discovered, the FDL was written by the FSF when they thought their business model was going to be selling books. Those were the days. The FSF also thought that O’Reilly had stolen their business model and they were pretty annoyed so they made their FDL a very very defensive license. It effectively stops any reuse of the material. It is a terrible license (which is why Wikipedia also got out of using it, but that is someone else’s story to tell).

At first, I used to be very dismissive of these license conversations. I was so sick of following them on the list, I tried to ignore them or stop them. Then I wrote an article about it. Eventually, I set up an additional licensing mailing list just for FM license discussions. I would encourage anyone that jumped into the main FM list talking licensing, to join that other list. I wasn’t subscribed to the FM license list, so it went on its own merry way and it didn’t slow the rest of us down. That was pretty effective.

Another issue that had the real potential for overriding community energy and tiring everyone out was the topic of One Laptop Per Child. At this moment OLPC was more like a religous movement than a technical endeavor. FM had done all their docs and they were distributed via an FM app on the OLPC. That was pretty cool really, and there were a lot of great people in the OLPC family. But the OLPC movement had the ability to also attract real Class A zealots. These were well meaning people, people who actually wanted to change the world. But they could go a ‘little’ too far down that road to the exclusion of all other concerns. This had the effect of derailing any conversation and was a major factor in lowering community energy. I had to work on the sidelines to corral those folk. There weren’t many, but they took some work. Staying positive and constructive was key.

Still, we did write a lot of material about the OLPC. We even had a number of pretty awesome Book Sprints about how to use the open source Sugar operating system it ran on.

Writing the OLPC docs in Texas. Anne Gentle far right.
Writing the OLPC docs in Texas. Anne Gentle, documentation guru, far right.

At the time, I read as much as I could about community building. However there wasn’t that much I found useful. I liked Karl Fogel’s Producing Open Source, and Jono Bacon’s The Art of Community. But much of what I read was about software development, not content development. It helped but not a great deal. I also mined the MIT archive on research about open source-related topics. At the time I think it was maintained by a buddy (Mako Hill) and it contained a lot of material about Wikipedia since that was the hot topic of the time. Still, not much helped. I also attended Wikimania a few times as the Wikipedia community seemed to be the most obvious source of information about how to build open content communities. The Wikimanias I went to were awesome and I learned a great deal talking to people. Of particular help was Brianna Laugher, Erik Möller and a few others. I also loved many of the presentations including one of my all time favorite presentations by Lawrence Liang on the authority of knowledge vs collaboration (which he later repeated at an Amsterdam conference and which is available here).

In short, I was hungry for information and tried to become the expert on building community. Any tool I could use, I wanted to know about.

As it happens, things worked out and FLOSS Manuals became a thriving community. The English community spawned a French community and both are still active. There was also (briefly) Finnish, Farsi, and Dutch communities. We did actually have a lot of material translated into (if I remember) about 30 languages but these were all ‘one offs’ and no language communities other than those mentioned above got off the ground.

French FLOSS Manuals crew.
French FLOSS Manuals crew.

I think I learned a lot from this period of my career. So what remains with me? Well, in terms of suggestions about what is important in building community this is what I have left off the top of my head, I hope it might be of use to someone:

  • have a starting point. Something others can join.
  • make the mission clear and simple. Make sure you feel that there is the possibility others will share the same point of view (even if you have to go out and find them).
  • don’t be a benevolent dictator. The longevity of a project means that there must be shared leadership. Otherwise, if you leave, it will fall apart.
  • take all the hard tasks away from the community and leave the easy, fun, stuff for the community to do.
  • do what you can to keep the community focused on the mission. Don’t allow distracting energies to override the community.
  • celebrate individuals in the community in public as much as you can
  • jump in to help as quickly as possible if a community member needs you.
  • work shoulder-to-shoulder with the community as much as you can.
  • find your protagonists, these people are in themselves community-building catalysts. Bring them in and make them feel at home.
  • make the efforts of the community as visible as possible to those it is trying to benefit.
  • be generous in attribution, including attribution for projects that are competitive to yours.
  • get out there and present the project in as many forums as you can.
  • internal energy is a product of engagement with others on the same mission, perceived momentum, and utility in this kind of community. You have to make these later two visible (momentum and utility) to your community to generate the former (engagement).
  • be careful not to overload people with your own enthusiasm.
  • as one of the leaders, it is all about you, and it is not at all about you.
  • communicate loudly and clearly the pride you have for the project and the pride you expect others to have in the project.
  • be careful with extrinsic incentives, they might not get you what you want.
  • don’t hold ‘what you have’ too close. Let it go and let it have its own life in the world.
  • don’t get discouraged if other projects, especially bad ones, get funding and support when you don’t. Stick it out.
  • forget about the competition, just do what you do well.

And as a happy coincidence, I found this advice I wrote somewhere between 2010 and 2012, which seems pretty right-on. It’s written from the perspective of managing a community of contributors for a book but it is obviously deeply informed by my experience building the FLOSS Manuals community. From:

Once you are up and running, energy needs to be put into the ongoing growth of the contributor base (assuming you haven't hit capacity) and energy needs to put into keeping the current contributors active and involved. Again, drawing a parallel between book development and code development - many open source projects have fulltime community managers. Jono Bacon1 is one such person - he is the community manager for Ubuntu and wrote the excellent Art of Community Book2 which is well worth reading -  but please keep in mind that book community management doesn't map directly onto free software community management.
Keeping the contributors involved can be a great job but it also has some gnarly issues. The vast majority of the work is social and some logistics - making sure that the technology for contributing is working and is not a burden for example. You might not have to do any tech work yourself in these cases but you will need to find the person who will. One thing that has almost universal value in this role is the ability to keep a one-to-one interaction feeling with active members of your community. You are a central pin in the entire mechanism and people like to be close to the action. Keep communicating with people, keep them talking, put them in contact with others working on similar issues, expand their network, in other words - keep it social.
In addition to this, another secret ingredient is fun. Don't make the mistake of taking things too seriously, and if you do, make sure that others don't see it. It's ok to blow your top occasionally - its actually good to be seen to be fallible -  however you should apologise as soon as possible and get the good feeling back in the air. For the most part, however, it is very important that the community enjoys the ambiance - it might seem an intangible 'fun factor' but its more likely that its carefully engineered by you than it 'just happens'.
Another very important issue is learning when and when not to channel attention and requests to members of the community. Those that are active will become natural pivots on the center of your community and it can turn into a burden for those core individuals if not managed with care. Make sure you are keeping an eye on their frustration levels - if you see they're getting too much of a load, put on them by normal community processes then you may need to step in and redirect or take on some of that traffic.
These core members are very important to the health of the project but don't be disappointed when they leave. Communities have natural cycles and, additionally, community members have other lives. When they inevitably move on, make sure you acknowledge them in front of the community - this is not only a good thing to do, it will relieve any disappointment you may feel and it will signal to the community that everyone is respected and valued as individuals - not just as production engines.
Also keep in mind that although natural hierarchies will evolve, it is quite important to keep the community in an egalitarian mindset. All contributions should be valued and all contributors should be valued. That also means that you must keep the balance of power even. Core contributors will naturally get more say in how things go but ensure that channels are open for all voices in the community to have their say. It is also for this reason that it is not a good idea to bring any publishing world hierarchical structures to community management. Don't think of editors and writers, think of collaborators and facilitators.

If people are enjoying themselves and enjoying the social environment, they are of course not necessarily being productive. My experience is, however, that people involved in this kind of project generally like being productive. If they are talking its usually a sign they are working.


Crazily, you can still buy the manual on FLOSS Manuals we wrote in 2008, here!

Google Sponsors Book Sprint

FLOSS Manuals فارسی

Google is to sponsor the second FLOSS Manuals Book Sprint.

The event will focus on bringing four free documentation writers together in Paris in July to write a manual on Inkscape, the popular vector graphics software. The team comes from France, The Netherlands and the USA to work together for a week at the Paris Cité des Sciences.

The Book Sprint will also be open to remote (IRC) involvement and the team is especially interested in French – English translators as much of the original content will be written in French. If you would like to participate please contact Adam Hyde (

Wireless Networking Book

FLOSS Manuals فارسی

This is a very good book: Wireless Networking for the Developing World

It’s open and free, developed by some people at WSFII.

I met Tomas Krag, one of the writers, at the Open Translation conference over the last few days. The book is very inspiring as a model for the type of sophistication of content achievable in free documentation, and also I found the model they used for creating the content very interesting.

Essentially, Tomas and the other authors met in London for an event. They paid a friend to go on vacation for a week and used their apartment. As I understand it, everyone stayed in the apartment and they spent the week designing the structure of the book and began writing it. The book was then completed with individual chapters written remotely by each other and submitted for editing and layout.

I think it’s a very interesting model, and perhaps one FLOSS Manuals should think about employing for creating material…

At the moment, the book they produced is not being maintained and I asked Tomas if he would consider hosting it on FLOSS Manuals.

Why You Should Love Free Documentation

FLOSS Manuals فارسی

First draft of an article for publication:

Free software has enjoyed many years of support from the cultural sector. Artists and activists have often been active in promoting free technologies. Artists also often make a living through teaching and workshops centred on free technologies they use in their practice. Curators of exhibitions, symposiums and festivals have followed these themes and brought these issues into the public arena. Theorists have published and lectured about the need to use and develop software and hardware which is free. The support has often risen to the point of hyperbole. There were many years when every event seemed to be ‘open’ this or ‘free’ that.

However, it seems that the uptake of free software, despite the efforts, is very slow. Although most of the internet runs on free software (60% of web servers run Apache and 90% of Domain Name Servers run BIND), if we look at operating systems the share is somewhere under 2%  (1).

Free software, as opposed to free operating systems, does a little better with the current estimate for Firefox usage across all platforms coming in at something between 20-30% (2).

Still, this is very small. The user penetration of Firefox is an impressive achievement, but why haven’t other fine tools such as the Gimp or Audacity taken a similar “market” share?

And why, given that we all know how good free software is, that a wide variety is available and that it is free, as in gratis as well as libre, is the uptake so low?

The Free Software Foundation thinks the answer is quite simple :
“The biggest deficiency in free operating systems is not in the software—it is the lack of good free manuals” (3).

Many years teaching free tools (mostly streaming) have taken me to the same conclusion.

It’s not that there is no documentation. Often you can find something, if not on a developer’s site, or in a bookstore, then perhaps comments in a forum, mailing list, or maybe in a wiki somewhere. This seems to satisfy most geeks. Many ‘advanced’ users tell me this is enough. Google is their index, and they know how to use it to find solutions. The thinking is that when it comes to solving a problem in software, you aren’t the first to have the problem and someone somewhere has written down a solution to it. This is often true. If it isn’t true, then either you solve the problem yourself (by hitting your head against the wall until it works), or you find the appropriate IRC channel and quiz the developers. Even better…you’re using open source, right!? READ THE SOURCE CODE!

Well, I don’t know about you, but perhaps my brain isn’t big enough or I maybe don’t have enough time, or maybe, just maybe, I feel that I should not have to be a programmer to work out how to use software. Perhaps this threshold is a little too high and might be deterring users… y’think?

Free software should be well documented. You should be easily able to find out what a software does, what it doesn’t do, how it fits into the software universe, what the interface looks like, how to install it, how to set the most basic necessary configuration, and how to use its main functions. These things should be well explained and kept in a place that is easy to find.

The easier it is to access well-written documentation the larger the potential user base.

I have also often heard that it is simply not the case that there is a lack of documentation. There is a manual for $X! (replace ‘$X’ with your favourite free software). What do you mean!? $X has a great manual!

Well, I admire the effort put into the documentation of some free software. Unfortunately, however, it is seldom adequate.  The most common flaws include :

  • assumptions about the user’s knowledge are set too high
  • bad navigation
  • unexplained jargon
  • no visual component
  • proprietary (‘closed’) material
  • unreadable design
  • steps missing or unexplained
  • documentation is out of date
  • documentation is not easily re-usable
  • documentation is not easily modifiable

These mistakes are very common, and the situation is so bad it amounts to a crisis in the world of free software. I have made my own efforts to combat this situation butmore contributions are needed. Perhaps a clear summary of the basic issues would encourage others to contribute to free documentation projects.

Free documentation for free software

I sometimes feel this is too obvious a point to make. Documentation which is freely available and so ideologically aligned with the [free] software,  seems to me to me to be a natural match.

Practically, however, there are a few hiccups with this idea. Free software has developed a methodology and economy which free documentation lacks. The traditional method of making money in the manual business is to write a manual and sell it. To protect your interests, you use a standard ‘closed’ copyright notice. This is the ruling publishing model. Outside of this circle, you do the best you can voluntarily, and put the content online for others to access, where ever you can.

The Free Software sector has much better resources and models. Free software projects have a number of management tools available including sites like Savannah and SourceForge, and they have established working models. The financial model is much clearer too. Most obviously if you need to make money working on a free software project you get good at it and find a company that will pay you to work on it in-house or by contract.

Free documentation lacks all these components – there is no standard technical tool set, very few ‘communities’ of free documentation writers ,and less chances of being able to pay the rent if you choose to do create such documentation full time.

Finding a way to build these elements is critical to the evolution of a healthy free documentation sector, and, I would argue, to achieving the widespread adoption of free software. It is imperative that we find these models and tools, as closed documentation for free software contains a ideological paradox.

On another point – less ideologically and more practically speaking – free documentation is better argument than closed documentation.   The closed nature of proprietary documentation is a disadvantage: the ability  to update documentation at the same time as the software is updated is a huge advantage. It can thus be updated, modified, improved a la ‘many eyes make bugs shallow’, translated into your own language, or re-contextualised to better suit individual or organisational needs. Free documentation on these terms alone is a better argument than closed documentation, and when done well can be a tremendous asset to the uptake of free software.

Free documentation should be easy to access and easy to improve

If something can be improved then it should be able to be easily improved. Many free documentation projects inherit their technology strategy from free software development methods. These projects store their content in a CVS which means that you need to be pretty technically competent to be able to access the source material and contribute to it.

What this overlooks is that writers are not programmers. Writers have a different tool set, usually word processors, and do not have a familiarity with the typical programming tool set. To expect a free documentation writer to access content via CVS or similar tools is to make the same mistake as assuming the audience for your documentation knows more than they do. Setting the threshold for contributions so high means that many people that could contribute won’t contribute.

There is no need to trap content in CVS. All we are dealing with is text and images and there are plenty of tools that are easier to use.  I recommend a wiki with WYSIWG (What You See Is What Yo Get) editing – these are online tools that look and work like word processors except they are available anywhere you can get online via your browser. I personally don’t recommend using mark-up languages as even wiki mark-up is harder to use than WYSIWYG editors and a barrier to contributions.

Well structured
Many projects are now setting up unstructured wikis for their developers and users to use for writing documentation. Often MediaWiki is used (although the wiki used depends on the winds of software fashion). These resources can be extremely good, however, I believe unstructured wiki content with a contextual navigation system, is a poor substitute for well-structured content with a clear top-level index. Unstructured content is a good secondary documentation strategy, and certainly good for documenting the ‘nooks and cranies’ of sometimes archaic interface issues or strange hardware-specific conflicts, however, it doesn’t replace content that is designed to document the software thoroughly with a clear and structured flow.

Tell it as it is
I have found that documentation written by developers makes the simple mistake of writing how the software should work and not how it does work. Writing free documentation should not be done from memory or by those that cannot see the problems. Telling the user what is wrong with the software, what does not work, what could be improved, is absolutely necessary. It’s not bad-mouthing a free software to point out a quirk that should not be a quirk. It is far worse for potential users of that software if the user reads documentation that is inaccurate or which glosses over these issues.

Make it look good
Documentation should be attractive to read. Free software developers have discovered over the years that in order to interface with humans, software must look nice and allow the eye to easily engage with it. The same is true for documentation. Black text with blue links on a white background is not enticing. Embrace a layout than enhances readability but makes sure it also looks good.

Now we come to the bugbear. Quality. What is good quality documentation? Well, there are some mechanical benchmarks :

  1. no spelling mistakes
  2. set a style guide and stick to it
  3. make sure no steps are glossed over
  4. make sure the documentation is accurate

However, beyond the mechanical there is the subjective issue of quality. There is no solid rule: the best you can do is to get people to read the content and tell you if it makes sense. If you belong to a community of contributors then look to peer reviews.

FLOSS Manuals and the Pursuit of Funky Docs

It is easy enough to point out what is wrong with something and harp on about how it should be. It’s another issue to actually do something about it.

To resolve this, I am involved in a not-for-profit foundation called FLOSS Manuals. We are a community of free documentation writers committed to writing excellent documentation about free software. Anyone can join FLOSS Manuals and anyone can edit the material we publish. All content is licensed under a free license (the GPL).

When we started (the actual point of genesis is hard to determine but we officially launched in October 2007), there was, and still is, no good publication platform for collaborative authoring. Some may say that there are too many Content Management Systems already and surely, SURELY, there must be a CMS to meet our needs?

Well, no. The closer you get to identifying the needs of collaborative publishing systems, the further you stray from the functionality of most Content Management Systems. So we have hacked our way into the wonderful TWiki and developed our own set of plugins. TWiki has proven to be a very good platform for online publication. It has all the structured content features and user administration that make it a good shell for authoring collaborative content. What was missing, and what is missing from other CMSes is good copyright and credit tracking, easy ways to build indexes, and a nifty way to remix content.

However, we have remedied that now with our own custom plugins (which are available through the TWiki repository). There are still some things we need, in fact it’s quite a long list, but piece by piece we are turning TWiki into a publication engine. Currently, we are working on translation workflow features (also in plugin form).

So, the word ‘remix’ may have caught your eye and you may have fleetingly thought ‘remixing manuals?!’. It might not seem intuitive at first glance but there are a lot of very good reasons why manuals are excellent material for remixing. I don’t mean remix in the William S Burroughs sense of cut-up… we do cherish linearity in the world of free documentation. I mean remix as in “re-combining multiple chapters from multiple disparate manuals to form one document.” Doing this enables you to create manuals specific to your needs whether they be for self-learning, teaching, in-house training or whatever purpose.

The FLOSS manuals remix feature ( enables the remixing of content into indexed-PDF and downloadable-HTML (in zip or tar compressed form) with your own look and feel (CSS). Now we have also added a Remix API. This means that you can remix manuals and include them in your website by cutting and pasting a few lines of HTML – no messy ftp necessary…

This part of FLOSS Manuals is new and in test form, but it works very well and the possibility for combining remix with print-on-demand is an obvious next step. It can be done now as print-on-demand services use PDF as their source material, but the trick is in getting it to look nice in print form…

Print on Demand
In addition to the free online manuals FLOSS Manuals material is also turned into books via a print-on-demand service. The books look very nice, having been tweaked to look good in print, and they are available at cost price (we don’t put any mark-up on the books so they cost what the print-on-demand company charge to produce and send to the buyer). This is pretty exciting and I hope that we will soon see FLOSS Manuals on the bookshelves of retailers: bookshops after-all are a very important promotional venue for free software.

I find that the books themselves actually get the idea of what FLOSS Manuals is doing very effectively to most people I talk to. Imagining a website is one thing, but handing over a book sparks the understanding and gets people excited. So books are an excellent promotional medium for FLOSS Manuals as much as for the software (it’s a symbiotic relationship after-all).

I imagine print-on-demand will play a bigger role in the future of FLOSS Manuals. There are many possible paths, but, in the end, it comes down to capacity and we are this stage a very small organisation. If you wish to get involved with this (exciting) part of our evolution then let me know…

Quality Control
Lastly, a word on quality. The manuals aim to be better than any available documentation (sometimes this is not hard as there is often no other available documentation!) Keeping this level of quality has some interesting issues when working with an open system. Anyone can contribute to FLOSS Manuals – it is completely open. You need to register but this is not a method for gating contributions, it is there so we can abide by the license requirements of the GPL to credit authorship. Additionally, credit should be given where contributions have been made so we also credit modifications in the manuals.

SPAM is an obvious issue with an open system, as is the possibility of malicious content. Incorrect or malicious information in Wikipedia might lead you to quote the wrong King of Scotland or may misinform yo7u about the origins of potatoes, but incorrect information in documentation might lead you to wipe out your operating system. So we separate the ‘back end’ – where you can write manuals – from the ‘front end’ – where you can read manuals.

Manuals in the ‘WRITE’ section ( are in constant development. However, the same manual linked from the front page will be in the ‘stable’ form. This is managed by some existing TWiki tools that we twisted together to form a simple one-step publishing system. It works like this – every manual has a Maintainer. A Maintainer is a person – a volunteer – that keeps an eye on that particular manual. Edits and updates carry on through the WRITE section by anyone that wishes to contribute. When the Maintainer thinks the manual is in good form and an update is appropriate, they push the ‘publish’ button and all the material is copied to the ‘front  end’ version of the manual.

This way, the reader gets stable reliable documentation, and the writers can continue working on those docs without the reader being confronted by half-finished content etc. It’s a simple and effective system.

How you can help
Good free documentation is a necessary component of all good free software. If you can’t program or don’t want to, but you love free software and want to help, then help make free documentation!

Knowing where to contribute is now easy! You can :
read manuals –
write manuals –
or remix manuals –

We have a growing number of very talented contributors and Maintainers and good manuals available online, but we need more manuals and more contributors. Contributing is pretty easy, and if you would like to be a part of helping create good manuals, then register with the project ( and read our manual on FLOSS Manuals (

Anyone can contribute. You can spell-check documents, tidy up the layout, suggest ways of improving docs, test/review material, design icons, write or improve any material. Contribute in any way that you can and you will be helping not only to make the documentation better, but you will be assisting in the development and spread of free culture and free software.

The State of Free Software Documentation

It’s often hard to find good writing about the state of online documentation. Andy Oram writes for O’Reilly OnLamp, and he has contributed a couple of very interesting articles on the motivations of free documentation writers, and the state of free documentation.

Why Do People Write Free Documentation? Results of a Survey was published on 14 June 2007 and contains some very interesting research results.

Although I found the results very interesting, it was the preamble that I found most worthwhile. The assumptions Andy makes about the current state of free documentation online echoes very closely the motivations for creating FLOSS Manuals. Andy outlines four issues that reflect the general state of online docs today :

  • The same questions get asked over and over
  • Users don’t know where to start
  • Information quality is uneven
  • Optimal solutions are often undiscovered

I agree with these issues, but there are two issues I think he overlooked :

Licensing Interoperability

The current licensing situation for free documentation is pretty bad, the main issue being that there is no standard license that everyone agrees to use for documentation on the web. This would not be such a problem if licenses were compatible, enabling the easy transition of content from one source to the other, and allowing the combining of material released under differing licenses. However, this is not the situation now, as Lawrence Lessig mentioned in 1995:

"Even if all the creative work you want to remix is licensed under a copyleft license, because those licenses are different licenses, you can’t take creative work from one, and remix it in another. Wikipedia, for example, is licensed under the FDL. It requires derivatives be licensed under the FDL only. And the same is true of the Creative Commons Attribution-ShareAlike license that governs Opsound content, as well as much of the creativity within Flickr. All of these licenses were written without regard to the fundamental value of every significant advance in the digital age — interoperability"

With free software, the GPL is the standard license, and since no such agreed ‘standard’ exists for documentation, then improving a document using multiple sources cannot occur.

FLOSS Manuals has decided to use the GPL. Since there is no ‘standard’ for docs (I have written about this in an earlier FLOSS Manuals post about the problems with the GNU Free Documentation License), then we might as well side with the programmers until this interoperability issue is resolved. Documentation is after all, often included with software, and it’s easier for programmers if they don’t have to worry about license compatibility problems between the documentation and the source code. However, one tactic we still might employ is to dual-license in Creative Commons so that bloggers etc could more easily copy and adapt documentation for their own use.

“It’s not a bug. It’s an undocumented feature.”

Andy Oram omitted the ever frustrating fact that often the documentation just doesn’t exist. This is always going to be the case as the first step of a software development project is seldom to write the user manual. Documentation is usually last on the to-do list, and sometimes it falls off the checklist all together. This might be understandable if the project was new. However, there are many times I have looked for documentation and found it doesn’t exist anywhere, even for relatively mature software. The only remedy for this is to hope that more software developers take documentation more seriously and develop a documentation team alongside their coding team. The other option is that community-led projects like FLOSS Manuals fill the gap. This is what we are trying to achieve but our efforts are only needed because the state of documentation online is so bad. In a better world, there would be no need for such an effort.

I enjoyed Andy Oram’s article very much and the results of the survey are well worth reading. You may want to map the findings against “What motivates Wikipedians: motivations for Wikipedia content contribution” (PDF) by Oded Nov. You can find more of Andy Oram’s writing here (thoroughly recommended):