[FM Discuss] article for 2 publications

Mon Nov 19 10:13:06 PST 2007

hey

I am going to send this short article about FM to a couple of cultural
publications, any comments welcomed (thanks to Andy for giving some
feedback already) 

====================
Why you should learn to love free documentation

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 centered 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 was 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 similar "market" share?

So...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 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” 3.

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

Its not that there is no documentation. Often you can find something, if
not on a developers 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 writen 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 a 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
favorite free software). What do you mean!? $X has a great manual! 

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

      * assumptions about the users 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 but I thought it is about time I wrote some of the
basic issues down 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.

Free documentation for free software

I sometimes feel this is too obvious a point to make. Making
documentation ideologically aligned with the software it documents seems
to me to me to be a natural conclusion. 

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
publishing model. Outside of this circle you either do the best you can
voluntarily and put the content online 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 inhouse or by
contract. 

Free documentation is lacking 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
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
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. Being
able to modify documentation is a strength that proprietary
documentation cannot match. Free documentation can be updated at the
same time as the software is updated, improved ala 'many eyes make bugs
shallow'4, 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 if
done well, can be a tremendous asset to the uptake of free software.

Ok...so, now I would like to talk a little about some things I think
good free documentation should have.

Free documentation should be easy to access and easy to improve

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 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 the fact that writers are not programmers.
Writers have a different tool set, usually 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 wont 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 that WYSIWYG editors and a barrier to contributions. 

Well structured

Many projects are now setting up unstructured wiki's for their
developers and users to use for writing documentation. Often mediawiki5
is used although the wiki used depends on 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 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. Its 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. 

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.

Quality

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

     a. no spelling mistakes

     b. set a style guide and stick to it

     c. make sure no steps are glossed over

     d. 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 Oct 2007), there was, and still is, no good
publication platforms 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 makes it a good shell for
authoring collaborative content. What was missing, and what is missing
from other CMS's 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, infact 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).

Remixing

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 a re 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 self learning,
teaching, inhouse training etc. 

The FLOSS manuals remix feature (http://www.flossmanuals,net/remix)
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 actually get the idea of what FLOSS Manuals is
doing better 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 (its 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
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 yo about
the origins of potatoes, but incorrect information in documentation
might lead you to wipe-out your operating system. So we separate the
'backend' – where you can write manuals – from the 'frontend' – where
you can read manuals.

Manuals in the 'WRITE' section (http://www.flossmanuals.net/write) 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 'frontend'
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. Its a simple and effective system.

How you can help

Good free documentation is a necessary component of 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 – http://www.flossmanuals.net

write manuals – http://www.flossmanuals.net/write

or remix manuals – http://www.flossmanuals.net/remix

We have a growing group of very talented contributors and Maintainers,
and number of very good manuals available online but we need more
manuals and more contributers. Contributing is pretty easy, and if you
would like to be apart of helping create good manuals then register with
the project (http://www.flossmanuals.net/register) and read our manual
on FLOSS Manuals (http://www.flossmanual.net/flossmanuals).

Anyone can contribute you can spell check documents, tidy up layout,
suggest ways to improve docs, test/review material, design icons, write
or improve material. Contribute in anyway 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.

1 http://marketshare.hitslink.com/report.aspx?qprid=2

2 http://www.w3schools.com/browsers/browsers_stats.asp

3 http://www.gnu.org/philosophy/free-doc.html

4 the so-called “Linus's Law” by Eric S. Raymond

5 http://www.mediawiki.org

-- 
Adam Hyde
FLOSS Manuals

http://www.flossmanuals.net