Booki Development Ecology

We are a small team working to change publishing together. Think of an environment where social networking features are brought to bear on the publishing industry. Social Publishing of sorts. That’s us…. Imagine the application for this kind of environment within Schools, NGOs, government, publishing etc. The possibilities are enormous. Now think of an organisation with no employees doing this for love while looking for ways to pay the rent…that’s us!

So we are looking to build a sustainable open source ecology around Booki. This means that we are interested in building relationships with organisations that have a need for Booki, either at http://www.booki.cc or as their own installation. We would like to work with these organisations through either :

  1. contracted programming to extend Booki
  2. consulting on technical issues
  3. consulting on Booki best practices or what the possibilities are for using Booki

In this way we hope to build an ecology of projects working around one code base and helping us pay the rent, buy food, pay for our early retirement plan 😉  In the past we have worked with Archive.org (for extending Booki to proof Archive.org ePubs) and Sesawe.net (for building bi-directional text output for book formatted PDF) in this way (contracted work to extend Booki).

If you see a need for Booki and would like to use it and contribute to the ongoing development of the platform, then please consider one of these possibilities and let us know.

Additionally, we are also seeking funding to help extend Booki, if you know of funding that might be appropriate then please also tell us!

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 (adam@flossmanuals.net).

Pure Data Book Sprint

FLOSS Manuals فارسی

In the first week of April, Luka Prinčič and Derek Holzer have been participating in the first FLOSS Manuals Book Sprint. The Sprint took Derek and Luka away to the beautiful island of Korcula to write a manual on Pure Data.

The idea stems from discussions with Tomas Krag from WNDW, and is based on ‘Code Sprints’. Code Sprints are gatherings organised by free software projects. At these gatherings, programmers spend time working together in an intensive working period to write as much code as possible. The important element is that it is a short intensive burst designed to be fun and productive.

The Pure Data Book Sprint is our first trial of this process and will be soon followed up by an Inkscape Book Sprint to be held in Paris in July

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.

Quality
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.