Many times I have searched online for information about how to use a particularly exciting free software and been disappointed about the lack of information I could find. This situation was particularly frustrating when it came to leading workshops. I wanted to spread the word on the wonderful applications available, from real time audio and video processing applications like PureData or Kino, through to office applications like Gimp or Inkscape. However I had to create my own manuals for my workshops as there was nothing else appropriate available online. Sure, some of these applications had books available which I could (rather expensively) purchase at the local bookstore, however I would have to require my students to buy the book too or rewrite (backward engineer) the material to avoid copyright infringement.
It seemed crazy to me that I had to buy a book to learn how to use a free software. The problem seemed not just financial but idealogical. How can a software be free if you have to buy a proprietary book to learn how to use it?
At first I thought this was just a gap in the free software ecology. Someone simply needs to write free manuals. As it turns out this is largely true, however there are a few embedded issues that need to be dug out before the free documentation sector can identify itself and flourish. Through observation and experience I have come to the conclusion that the free software / open source sector has a blind spot when it comes to documentation which is retarding the development of this sector. This prejudice begins with a general belief that documentation is not that important and extends to much more extreme positions such as the Free Software Foundations inability to extend the same license freedoms for documentation as they extend to software.
In time this will change as more people realise that free documentation is not just an important promotional tool for the advancement of free software, but that free documentation is as socially and economically empowering, and subscribes to the same ideals, as free software itself.
In this article, I'll describe what I see as problems with existing free software documentation, licenses, and delivery mechanisms. Then I'll describe attributes I think free documentation should have, along with the economic ecology that it needs. Finally, I'll talk about how the FLOSS Manuals Foundation is attempting to address these issues, and how you can help.
Free software has developed outside and alongside of the more restrictive licenses and copyrights of the proprietary software environment. (i) Free software can be used by anyone for any purpose: users can study the source code, adapt it to their needs, and whether or not they modify it, they can redistribute both the software and its source code. This co-operative model has meant that free software has had a high rate of uptake in the cultural sector - artists and activists have been amongst its active promoters. Its appeal is strong amongst those who recognise the productive political and social ambiguity of the word 'free'. A number of artists also make a living through teaching and workshops centered on free technologies they use in their practice. Exhibitions, symposiums and festivals engaging with these ideas have brought these issues into the public arena, while cultural and digital theorists have reinforced the need to develop and use both free software and free hardware. This support has often risen to the point of hyperbole, and for many years every digital art event seemed to be 'open' this or 'free' that.
However, despite these efforts, it seems that the uptake of free software 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%. (ii) Free software, as opposed to free operating systems, does a little better, with the current estimate for usage of the Firefox browser across all platforms coming in at something between 20-30%. (iii) Still, this is very small. The user uptake of Firefox is an impressive achievement, but why haven't other fine tools such as the image editing software Gimp or the audio editing software Audacity taken similar 'market' share? 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, (or, Free Libre Open Source Software - FLOSS) is the uptake so low?
The Free Software Foundation think 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." (iv)
Many years of teaching free tools (mostly for streaming media) have led me to the same conclusion. It is not that there is no documentation. Often you can find something on a developer's site, or in a bookstore, or perhaps in the comments on a forum, a 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 encounter it and that someone somewhere has written down a solution. 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 maybe, just maybe, I feel that I should not have to be a programmer to work out how to use a particular piece of software. Perhaps this threshold is a little too high and might be deterring users.
Free software should be well documented. You should be easily able to find out what a particular 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 up most basic 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 for a given software, the larger the potential user base.
I have often heard that it is simply not the case that there is a lack of documentation. 'There is a manual for XX!' (replace 'XX' with your favorite free software). 'What do you mean? XX has a great manual!' Well, I admire the effort put into the documentation of some free software. Unfortunately however, the documentation is seldom adequate.
There are some very good manuals available at a price for some of the more well known free softwares. In general there is more published about server-side softwares than desktop software. These books are usually published in the traditional publishing model under restrictive copyright with no easy way to modify or re-use the contents. I don't subscribe to using closed documentation for these reasons and other idealogical and practical reasons which I outline later in this article.
The most common flaws of existing documentation of free softwares include:
that assumptions about the user's knowledge are set too high
the documentation has bad navigation
it contains unexplained jargon
there is no visual component
the documentation is proprietary or 'closed' material
the documentation's design is unreadable
operational steps are missing or unexplained
the documentation is out of date
the documentation is not easily re-usable
the 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 address this situation but I thought it is about time I wrote about some of the basic issues in order to encourage others to consider the importance of free documentation and to encourage you to contribute to free documentation projects.
First of all I want to say something briefly about why documentation should be free, and then to look at some parameters for identifying good documentation.
Making documentation ideologically aligned with the software it documents seems to me to be a natural relationship. Documentation should be able to flow as freely as the software itself, making unhindered migrations across media, onto the screens and bookshelves of anyone that wants it. Documentation should be able to be redistributed, altered, sold or given away for free by anyone to anyone. If documentation cannot do this, it is not free.
It is with regret that author notes that the Free Software Foundations "Free Documentation License" [sic] tethers content to an unwieldy set of requirements which impede this freedom. The Debian Foundation has made many critiques of the license and they have concluded :
"It is not possible to borrow text from a GFDL'd manual and incorporate it in any free software program whatsoever. This is not a mere license incompatibility. It's not just that the GFDL is incompatible with this or that free software license: it's that it is fundamentally incompatible with any free software license whatsoever. So if you write a new program, and you have no commitments at all about what license you want to use, saving only that it be a free license, you cannot include GFDL'd text.
The GNU FDL, as it stands today, does not meet the Debian Free Software Guidelines. There are significant problems with the license, [...] and, as such, we cannot accept works licensed under the GNU FDL into our distribution."
http://people.debian.org/~srivasta/Position_Statement.xhtml
However it is perhaps the rationale of this license - marrying documentation to manual, manual to book, book to publisher, publisher to commerce - which has set the Free Software Foundation on a course that undermines their reputation as staunch defenders of freedom.
In particular :
the FDL does not allow for easy duplication and modification (an absolute necessity in this day and age)
it does not allow for the easy inclusion of documentation in software itself
it appears to be written for hard copy books and does not engage issues of digital documentation very well
it is difficult to know how to implement
These issues emanate from the founding rationale of the license. There are two particular assumptions that lead to problematic clauses:
1. The FDL seems to assume that technical writing should contain embedded free software political editorial. I refer to this statement (amongst others):
"Our manuals also include sections that state our political position about free software. We mark these as "invariant", so that they cannot be changed or removed. The GFDL makes provisions for these "invariant sections".
http://www.gnu.org/licenses/gpl-faq.html#WhyNotGPLForManuals
Political editorial is not a prerequisite (nor, in my opinion, desired) for good technical writing.
2. the FDL assumes documentation writing is a book business. I refer to :
"the GFDL has clauses that help publishers of free manuals make a profit from selling copies"
http://www.gnu.org/licenses/gpl-faq.html#WhyNotGPLForManuals
'Free Licences' should not shy away from commercial use of the substance it is applied to. That is the principle of freedom - to use the software or documentation as you wish, as long as you preserve the same freedoms for others. However the focus should be about preserving freedom not preserving particular business models. Can you imagine a similar clause in the GPL? It would be lambasted by Richard Stallman and the FSF for limiting freedom and immediately dropped. A pity neither Richard Stallman or the FSF apply the same freedoms to the materials of free software education. If they did this issue and others would be cleared up quickly I am sure.
The above are just the main concerns with the rationale of the FDL. These two issues have both idealogical and pragmatic consequences that make it very difficult to use the FDL if you wish to write free documentation for free software.
The idealogical issues are clear - but these rationale also simply make the license practically unusable. For example, there are constant references to book elements such as 'Title Pages', 'Covers' etc. One particular clause that is hard to maintain is this section which stipulates that a modified version of a work must:
"A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission."
There are so many issues with this statement its hard to know where to begin. What, for example, is the role of a 'History Section' in documentation that might be one 'page' long? What about documentation that is a few sentences long? The main problem with this clause however is that digital documentation should flow like water from one author to the other with as much flexibility to add, alter, delete, and remix as much as possible. Requiring a 'traceback' to the original author so you can use the same title is cumbersome, stifles re-use of material, and logistically hard to maintain in this age of free flowing digital document distribution.
Here is another 'book' issue which limits freedom:
" If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects."
Why should free documentation writers care how many documents you might print? In my case I want the material to be used as much as possible. Go ahead, print as many as you like, however you like, on whatever medium you like. Free documentation writers don't want to get involved in complex clauses involving 'Cover Texts', 'Front-Cover Texts' and arbitrary numerical limits which are going to limit your freedom to use the documentation as you want. They want the material to be used as much as possible.
We need the same principles of freedom for documentation as we have for code and the Free Documentation License (FDL) does not preserve the above principles of freedom. At the time of writing there is a redraft of this license and it looks like it will be split into two licenses, however neither of the redrafts address these fundamental issues. We need a license that goes further that the FDL and can allow the users to do with the documentation as they can do with the source code. Thankfully there is a license that does this - the General Public License (GPL). This is the license that most free software / open source projects use to release their source code. Due to the well known history and legacy of the GPL many believe it to be only applicable to software, however the license can be applied to any content as the FSF itself acknowledges :
"any work of any nature that can be copyrighted can be copylefted with the GNU GPL." http://www.gnu.org/philosophy/nonsoftware-copyleft.html
Documentation of free software should share the same principles of freedom as the software itself. It should therefore use the GPL when the code of the project it documents is also under the GPL. If you are not convinced of this idealogical argument then ask yourself these two simple pragmatic questions. Should programmers be able to benefit from the efforts of free documentation writers by embedding their documentation into the software itself? Should it be possible to distribute free documentation with the software it documents? If your answer is "yes" to either of these then you do not have many choices when it comes to licenses. License interoperability (compatibility) is laden with complex problems that few outside of the Software Freedom Law Center seem to understand. Many, for example - the Debian project, argue very convincingly that the Free Documentation License may not be compatible with the GPL. There is, however, one license that enables documentation to be easily distributed with GPL software - the GPL. The only reason to bother about another license is if the free software project you are documenting uses a license other than the GPL. In this case give the documentation the same license as the code.
Less ideologically and more practically speaking, free documentation presents a better kind of documentation than closed documentation. Ease of modification is a strength that proprietary documentation cannot match. Free documentation can be updated at the same time as the software is updated and improved through distributed problem solving (a la 'many eyes make bugs shallow'(v), it can be translated into your own language or re-contextualised to better suit individual or organisational needs. Free documentation in these terms alone is a better argument than closed documentation and if done well, can be a tremendous asset to the uptake of free software.
So, now I would like to talk a little about some essential qualities good free documentation should have :
It makes sense that if the intention is that something can be improved that 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 (Concurrent Versioning System) which means that you need to be pretty technically competent to be able to access the source material and contribute to it.(vi)
What this system overlooks is the fact that writers are not programmers. Writers have a different tool set (usually based on word processors), and do not have a familiarity with the typical programmers 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 You Get) editing - these 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 that WYSIWYG editors and is a barrier to contributions.
Many projects are now setting up unstructured wikis for their developers and users as a base for writing documentation. At the moment, mediawiki is often used, although which specific platform gets used tends to depend on the winds of software fashion. These resources can be extremely good, however I believe unstructured wiki content, with contextual navigation systems, is a poor substitute for well-structured content with a clear top-level index. Unstructured content is a good secondary documentation strategy and certainly useful for documenting the nooks and crannies 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.
I have found that documentation written by developers can make 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 done by those who cannot see the problems. Telling the user what is wrong with the software, what does not work and what could be improved is absolutely necessary. It is 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 glosses over these issues.
Documentation should be attractive to read. Over the years, free software developers have discovered 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 are not enticing. Embrace a layout than enhances readability but make sure it also looks good.
Now we come to the bugbear. Quality. What is good quality documentation? Some benchmarks include:
no spelling mistakes
set a style guide and stick to it
make sure no steps are glossed over
make sure the documentation is accurate
However, beyond the purely procedural 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.
Before talking a little about what FLOSS Manuals has done addressing the issues listed so far, I want to talk a little about the need for a free documentation sector.
Free software has developed a methodology and economy that 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 publishing model. Outside of this circle of proprietary content you do the best you can voluntarily and put your work online wherever you can.
The free software sector has much better resources. Free software projects have established working models and a number of content and management tools including development and distribution sites like Savannah and SourceForge. The financial model is much clearer too. Most obviously, if you need to make money working on a free software project you hone your skills and find a company that will pay you for your work.
Free documentation is lacking all these components - there is no standard technical tool set, there are very few 'communities' of free documentation writers and less chances of being able to pay the rent if authors choose to do this full time. Finding our 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 and develop these models and tools, as the standard model of closed documentation for free software contains an ideological paradox.
We need to build an ecology around free documentation in much the same way as the free software sector has done. Free software enables programmers to work with communities of programmers, with tools that enable collaboration, and the opportunity to learn from their peers.
There is an economy of reputation at work in these communities which encourages best practices, and a lucky minority can leverage their reputation to be paid to work on free software projects.
Free documentation needs these tool sets, communities and economies. Free documentation needs to identify itself as a sector and build a consciousness as a community. This in itself can lead to better documentation and to the potential for an economically sustainable practice for individuals wishing to make a living writing free manuals.
There are a few shallow myths about documentation that hinder this sectors development a little. The first is that writing documentation is boring. Well, it can be boring, but it can be hugely satisfying and it certainly can be fun. I have indeed actually witnessed people being happily proud of their docs and equally excited when someone comes along and improves them. Sound familiar? It sounds a little like the free software sector. Yes, documentation writers enjoy what they do, they enjoy doing a good job, they enjoy getting better at it, they enjoy being recognised for it, and they especially enjoy people benefiting from their efforts.
There is another myth that needs to be popped. I have noticed a certain amount of hesitancy in the free software world towards contributing to free manuals. This seems to stem from programmers holding onto the belief that writing a book is a cornerstone of the free software economy. Well, I hate to break the news here, but the publishing world is going through the same massive challenge to this commodity model as the other industries that have their medium digitised. Not that book sales which relied on proprietary content and the sale of information, ever actually made many authors much money but there is a bigger issue at play. Many programmers fail to see that the world of publishing has changed. It is not just software, music and movies that routes itself around artificial obstacles to distribution - books do too. If programmers hold on to outmoded models of proprietary information resale then they will find themselves without a secondary revenue stream The new model is, as technical writer Janet Swisher says, to "charge for time, but give away the artifacts".
The same situation is true for documentation writers in general. It is entirely possible to be commissioned, for example, to write manuals, or to be employed by a company to write inhouse support docs that can also be contributed to the general community under a free license. As with this example, in many instances the free documentation economy can map directly onto, and learn from, the economy that has developed around free software. It could be argued that the software is already there but the documentation largely isn't so the potential demand is very high.
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. In order to address this, I founded 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 (GNU General Public Licence)).
When we started (we officially launched in October 2007) there were, and still are, no good publication platforms for collaborative authoring. Some may say that there are too many CMS (Content Management Systems) already and surely, SURELY, there must be a CMS to meet our needs?
Well, no. The closer you get to 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 plug-ins. TWiki has proven to be a very good platform for online publication. It has all the structured content features and user administration that makes it a good shell for authoring collaborative content. What was missing, and what is missing from other CMSs is good copyright and credit tracking, easy ways to build indexes, and a nifty way to remix content. We have remedied that now with our own custom plug-ins (available through the TWiki repository). (vii)
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 the user to create manuals specific to their needs whether they be, for instance, learning by themselves, teaching classes or running inhouse training programmes.
The FLOSS manuals remix feature (http://www.flossmanuals,net/remix) enables the remixing of content into indexed PDF and downloadable HTML with your own look and feel provided by Cascading Style Sheets. Now we have also added a Remix Application Programming Interface. This means that you can remix manuals and include them in your website by cutting and pasting a few lines of HTML. No longer is messy FTP necessary. This part of FLOSS Manuals is new and in test form, but so far it works very well. Combining remixing with print-on-demand is an obvious next step. It can be done now, as print-on-demand services use PDFs as their source material, but the trick is in getting it to look nice on paper.
A word on remixing - if you want to make documentation that is reusable then consider the way you write it. It is a good idea to keep it modular - with no dependencies on other content and with as little single-context language as possible.
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 for print production, and they are available at cost price (we don't put any mark-up on books so they cost what the print-on-demand company charge to produce the book and send to the buyer). This is pretty exciting and FLOSS Manuals has its own embeddable Book Store Widget (http://www.flossmanuals.net/bookstore). Anyone wanting to support the promotion and uptake of free software can embed the FLOSS Manuals book store on their website with the addition of a few short lines of HTML.
As I talk to people, I find that the physicality of books is the best way to get across the idea of what the FLOSS Manuals project is doing. Talking about a website is one thing, but handing over a book sparks understanding and gets people excited. Books are an excellent promotional medium for free software itself.
Lastly, a word on quality. These manuals aim to be better than any available documentation. (Sometimes this is not hard, as there is no available documentation!). When working with an open system maintaining this level of quality raises some interesting issues. Anyone can contribute to FLOSS Manuals - it is completely open. You need to register, but this is not a method for gating contributions, but so we can abide by the license requirements of the GPL to credit authorship.
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 you about the origins of potatoes, but incorrect information in documentation might lead you to wipe-out your operating system. So we have separated the 'backend' - where you can write manuals - from the 'frontend' - where you can read manuals.
Manuals in the 'Write' section are in constant development. (viii) However, the same manual linked from the front page will be in the 'stable' form, ready for use. This is managed by some existing TWiki tools 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 are added to the Write section by anyone that wishes to contribute. When the Maintainer thinks the manual is in good shape and an update is appropriate they push the 'publish' button and all the material is copied to the 'frontend' version of the manual. This way the reader gets stable reliable documentation and writers can continue working on documents without the reader being confronted by half-finished content. It's a simple and effective system.
Good free documentation is not just a necessary component of good free software, it is the most important part of bringing the software to the largest potential user base. Free documentation is simultaneously a education tool and a marketing device - without it the software will undertake a gradual growth as users inform each other as to what is available and pass on experience and knowledge to each other on an almost one to one basis. This is a powerful mechanism in its own right but to break beyond this barrier into the world of the average desktop computer user we need comprehensive and attractive free docs.
If you love free software then join us making free documentation! We have a growing number of very talented contributors and Maintainers and good manuals available online, but we need more. Contributing is pretty easy. 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. (ix).
Anyone can contribute: you can spell check documents, tidy up layout, test or review material, design icons, write, remix or improve material. Contribute in any way that you can and not only will you be helping to make the documentation better, you will be assisting in the development and spread of free culture and free software.
http://www.flossmanuals.net/register
There has been error in communication with Booktype server. Not sure right now where is the problem.
You should refresh this page.