[iDC] Free Manuals for Free Software

[adam hyde]

hey

Thanks Biella for the feedback. 

On Sun, 2008-10-05 at 20:07 -0400, Gabriella Coleman wrote:
> Hi Adam,
> 
> This may be my personal bias as I am familiar with Debian politics, but 
> why not be much more specific about Debian's critique of the FDL? You 
> only mention it in passing.
> 
> It seems to me that you can significantly strengthen you own position by 
> drawing from the existing and pretty trenchant critique of th FDL. The 
> debate, which was really vibrant in 2005/2006 (if I remember correctly) 
> really produced some interesting material, which then culminated in a GR 
> (http://www.debian.org/vote/2006/vote_001). It also seems imperative to 
> couch your own critique within the "native" critique that has come out 
> of the field of F/OSS proper.
> 

I was trying to avoid that argument a little because Debian seemed to
endorse the FDL as long as 'invariant sections' were not present in the
text. My point is that the FDL is more fundamentally crippled because of
its embedded rationale - to support a small business publishing model.
It seemed to me that Debian critiqued the formal legal freedoms and gave
the license a 'pass' under certain circumstances without addressing the
tangled rationale that makes the license a real mess. 

However maybe I missed something in the Debian vote and discussion. I
will go back over it and have another look.


> Otherwise, I agree with what you say. I just think it could be made 
> stronger by gesturing to pre-existing critiques that have been launched, 
> discussed, and rediscussed almost ad nauseum  and might really contain 
> some great insight (and if nothing else, great quotes!)

ok! I will go through it again and see what I can dig up :) thanks!

adam



> 
> Biella
> 
> .adam hyde wrote:
> > hi,
> > 
> > I have been etching this article on and off for a bit. I'm posting here
> > in hope of some feedback...I think it might be a too heavy on the
> > critique of the Free Documentation License and too light on the final
> > hail to action. I'd be very interested in any comment on these points
> > and any other criticisms are also very much appreciated.
> > ------------
> > 
> > ==============================
> > Free Manuals for Free Software
> > ==============================
> > 
> > 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 ideological.
> > 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 free documentation can 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 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.
> > 
> > 
> > **The State of FLOSS Docs**
> > 
> > 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 on the desktop 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.
> > 
> > **Free documentation for free software**
> > 
> > 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. 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
> > preservingparticularbusiness models. Can you imagine a similar clause in
> > the GPL? It would be lamblasted 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 if that license
> > permits, otherwise just use the GPL. 
> > 
> > 
> > **Free documentation is better**
> > 
> > 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 :
> > 
> > 
> > **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
> > (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. 
> > 
> > 
> > **Free documentation should be well structured**
> > 
> > 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. 
> > 
> > 
> > **Tell it as it is**
> > 
> > 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. 
> > 
> > 
> > **Make it look good**
> > 
> > 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. 
> > 
> > **Quality**
> > 
> > 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.
> > 
> > **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. 
> > 
> > **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. 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)
> > 
> > **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 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 Programme 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. 
> > 
> > **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 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 I hope that we will soon see FLOSS
> > Manuals on the bookshelves of retailers. Bookshops are, after all, a
> > very important promotional venue for free software.
> > 
> > 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. So books are an excellent
> > promotional medium for FLOSS Manuals as much as for the free software
> > itself (it is a symbiotic relationship after all). 
> > 
> > 
> > **Quality Control**
> > 
> > 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.
> > 
> > **How you can help**
> > 
> > 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.
> > 
> > 
> > 
> > 
> > 
> > i The free software definition outlined by the Free Software foundation,
> > founded by Richard Stallman in 1984 emphasises that free software “is a
> > matter of liberty, not price,” and explains that “to understand the
> > concept, you should think of ‘free’ as in ‘free speech,’ not as in ‘free
> > beer.’” http://www.fsf.org/licensing/essays/free-sw.html The term
> > ‘FLOSS’ (Free, Libre, Open Source Software) emphasises both free as in
> > speech and free as in beer.
> > 
> > 
> > ii http://marketshare.hitslink.com/report.aspx?qprid=2
> > 
> > 
> > iii http://www.w3schools.com/browsers/browsers_stats.asp
> > 
> > 
> > iv http://www.gnu.org/philosophy/free-doc.html
> > 
> > 
> > v The so-called “Linus’s Law” is described by Eric S. Raymond in “The
> > Cathedral and the Bazaar”
> > http://www.catb.org/~esr/writings/cathedral-bazaar/cathedral-bazaar/
> > 
> > 
> > vi For example http://www.nongnu.org/cvs
> > 
> > 
> > vii 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 in plugin
> > form. http://twiki.org/
> > 
> > 
> > viii http://www.flossmanuals.net/write
> > 
> > 
> > ix http://www.flossmanuals.net/register
> > 
> > 
> > 
> 
> 
-- 
Adam Hyde
Founder FLOSS Manuals
http://www.flossmanuals.net