Weekly Edition
Return to the Front page
| |||||||||||
User manuals for free softwareDocumentation for free software is generally a problem area, both for users and developers. But developers at least have the code to consult, whereas most users are left poking around through menu items and consulting multiple web pages. The FLOSS Manuals project is using techniques similar to those used in free software development to produce manuals for users. The project seeks to create the kind of manuals that users may be used to from proprietary software packages. The project's About page describes the manuals being produced:
FLOSS Manuals make free software more accessible by providing clear
documentation that accurately explains their purpose and use. Each manual
explains what the software does and what it doesn't do, what the interface
looks like, how to install it, how to set the most basic configuration
necessary, and how to use its main functions. To ensure the information
remains useful and up to date the manuals are regularly developed to add
more advanced uses, and to document changes and new versions of the
software.
There are a wide variety of manuals in progress, covering graphics and audio tools, OpenOffice, Firefox, WordPress for blogging, and more. The most recent addition is a set of eight manuals for the One Laptop Per Child XO. These were created as part of a XO/Sugar book sprint held in August in Austin, Texas. The manuals cover the XO hardware and Sugar interface as well as six different activities that are available as part of Sugar. The use of a "sprint" is just part of the adoption of free software development strategies. The project is set up to allow for collaborative development by a community. FLOSS Manuals describes it this way:
The manuals on FLOSS Manuals are written by a community of people, who do a
variety of things to keep the manuals as up to date and accurate as
possible. Anyone can contribute to a manual – to fix a spelling
mistake, to
add a more detailed explanation, to write a new chapter, or to start a
whole new manual. The way in which FLOSS Manuals are written mirrors the
way in which FLOSS (Free, libre open source) software itself is written: by
a community who contribute to and maintain the content.
The manuals themselves are available in a variety of formats: HTML, PDF, as well as dead tree. One of the more interesting features is the remix capability. Using an AJAX interface, one can pick and choose from the chapters of existing manuals to create a custom manual that includes only the pieces required for some group of users. Remixers can choose their own cover and title, then export it all as a PDF file. Instead, one can also cut and paste some javascript code into a web page that creates a reader application on the page. In this way, the custom manual will always be up-to-date with the latest changes made to the chapters. FLOSS manuals clearly fill a niche that is needed in the free software world. The manuals have a rather professional look that will immediately stand out to users. There is a lot of work to be done, but it would appear that the project has made an excellent start. As one might guess, it is always looking for more interested folks to write, edit, and proofread manuals. (Thanks to LWN reader David Farning for suggesting we look at this project.) (Log in to post comments)
User manuals for free software Posted Sep 25, 2008 3:31 UTC (Thu) by flewellyn (subscriber, #5047) [Link] As a model for how a good manual should be written and organized, I think the PostgreSQL manuals would be perfect. I have yet to find a free software project which had better documentation; the manuals for the whole system are comprehensive, approachable, easily read and understood, with clear explanations and examples. It's simply the best documentation for any software system, free or proprietary, that I've yet read.
User manuals for free software Posted Sep 25, 2008 4:12 UTC (Thu) by tnoo (subscriber, #20427) [Link]
Django has excellent documentation, that seems to be written together with the
code.
Linux technology reference: Posted Sep 25, 2008 4:23 UTC (Thu) by constantine (guest, #53664) [Link]
http://www.makelinux.net/reference
is attempt to collect and organize all existed Linux and FOSS documentation to single knowledge tree. Your comments are welcome.
User manuals for free software Posted Sep 25, 2008 13:51 UTC (Thu) by sbergman27 (subscriber, #10767) [Link]
I was going to mention Django but you beat me to it. Actually, my whole Django development stack (Django, Python, PostGreSQL, JQuery) has ecxellent documentation through and through, and I can concentrate on doing my work. Unlike certain other development environments I've used where I spent more time mucking around trying to figure out how some api call is supposed to work based on a sketchy user-provided example use-case from a previous release on a poorly maintained wiki... as the devs, who felt that writing documentation was below their station, talked amongst themselves about how cool release x+1 was going to be. That framework has all but tanked as Django flourishes.
Good documentation is one of the hallmarks of a successful project. And in my experience, if the quality of the documentation is poor early on in the project, it stays that way, no matter how much lip-service gets paid to improving it on the mailing list. Users should not waste too much time waiting and hoping that a poorly documented product will get better. Making a clean break and finding something else usually saves *much* time and frustration in the long run.
User manuals for free software Posted Sep 25, 2008 23:47 UTC (Thu) by giraffedata (subscriber, #1954) [Link] as the devs, who felt that writing documentation was below their station, talked amongst themselves about how cool release x+1 was going to be. I don't think they felt writing documentation was below their station; they felt it was boring. As they get paid the same to do boring writing as to design and code the cool new release, the choice is obvious.
User manuals for free software Posted Oct 2, 2008 3:53 UTC (Thu) by dirtyepic (subscriber, #30178) [Link]
And answering the same question about some underdocumented piece of the API for the twenty-first time this month is less boring? ;)
User manuals for free software Posted Sep 25, 2008 7:38 UTC (Thu) by DonDiego (subscriber, #24141) [Link]
I'm very happy with the documentation of Subversion, which was inspired by the excellent documentation for CVS, and has in turn inspired the documentation for Mercurial.
User manuals for free software Posted Sep 25, 2008 7:46 UTC (Thu) by ca9mbu (subscriber, #11098) [Link] I would also highly recommend the documentation for SQLAlchemy. It's clear, well structured and accurate.
hmm Posted Oct 1, 2008 18:04 UTC (Wed) by wilck (subscriber, #29844) [Link]
How would this be any better than tldp.org?
At first sight, the stuff at flossmanuals is basic - very, very basic.
Look at the openoffice.org "documentation" on flossmanuals. It explains what word processing and spreadsheets are. How many people out there need to be taught that? There probably are some, but how high are the odds that they know about the flossmanuals web site and how to read it?
There is plenty of basic documentation (GNOME and KDE), and there is plenty of high-level docs (man pages) for most packages. What's missing is the mid level, stuff that helps people between the "absolute newbie" and "guru" levels. And speaking about tldp, there are too many outdated manuals and HOWTOs around. The worst problem nowadays is that if you search the web for a problem, you are likely to find hundreds of links to outdated, often even misleading or wrong information.
What's the point in creating a new portal? Why not just improve the existing portals by adding and updating information?
hmm Posted Oct 2, 2008 13:20 UTC (Thu) by adamhyde (guest, #54469) [Link]
I think many 'advanced users' don't believe that there are others that need more information than they would need to learn something. For example, there are plenty of people in the advanced western economies that do not know what an operating system is. This might surprise you, and many of the readers of lwn.net, however I have listened many times to very smart people talk about how they use a computer and it is clear many do not understand the relationship between the software they use and the operating system they use. They see it all as more or less 'the computer'.
Once you get outside these wealthy nations the situation changes dramatically of course. There are many people in the world that are encountering a computer for the first time via the OLPC project (amongst others). More still that will never see a computer in their lifetime.
My point is, there is a sliding scale of understanding about computers. If we wish to bring people into the sphere of free software then we have to realise that the largest potential market, and the nearest to conversion, is the average user - one that might know what 'online music' is, but doesn't know an 'audio file' from an 'mp3'. The free software sector has to talk to these people in a way they understand if we really want to see free software on every desktop.
hmm Posted Oct 2, 2008 13:41 UTC (Thu) by wilck (subscriber, #29844) [Link]
Sure, some people need to learn basics. I spent ours trying to teach my mom how to move a mouse. But again my question: How would such a person know about "flossmanuals.org"?
And then... people without any clue will usually have a person (teacher, coach) who explains their new device to them. These people will teach them what you can do with a word processor or spreadsheet. From my experience, children understand these things extremely quickly - once it has been explained to them, they won't need to reread the lesson on flossmanuals.
What we really need is teachers and coaches who tell people about "word processors" "spreadheets" and "presentations" rather than "Word", "Excel", and "Powerpoint". It's really unfortunate that these MS products have become synonyms for their respective functionality in everyday language.
What we need even more is professional-grade documentation covering the gap between OLPC children and freaks who read the source. We need that documentation in many languages on the same level of readability and accuracy as in English.
I recently tried to find a good, comprehensive tutorial on writing Openoffice.org macros. Still didn't find anything (I recall an article in a German Linux magazine some time ago, or do I need to buy a book?). If I had looked for Excel Macro tutorials, I'd found a dozen immediately.
hmm Posted Oct 2, 2008 14:38 UTC (Thu) by adamhyde (guest, #54469) [Link]
Well FLOSS Manuals provides books too. Our aim is to get to as many people as we can. One method is to have books available in Book Stores as these are excellent promotional avenues.
Since you mention OLPC and how to bridge the gap I thought you might be interested in this:
Its the sugar manual we have made in FLOSS Manuals which covers how to use the Sugar desktop on the OLPC. It includes chapters on using a terminal, basic python etc...this is one example of how documentation can help bridge this gap. This manual is also available completely free here:
hmm Posted Oct 3, 2008 15:30 UTC (Fri) by jmswisher (guest, #54501) [Link]
> At first sight, the stuff at flossmanuals is basic - very, very basic.
> What's the point in creating a new portal? Why not just improve the existing portals by adding and updating information?
A lot of the documents at flossmanuals, like for openoffice.org, are placeholders to show what is possible, rather than being "the" documentation for a project. I agree there is no point in duplicating effort for projects like OOo that already have robust documentation sub-projects.
Readers don't need to know about flossmanuals.net, because it provides hooks so that you can feed a document to your own website. So you can use flossmanuals on the backend to edit your docs, and the updates automatically show up on your project website.
The point in creating a new portal is to create a platform that makes it easy to create documentation for a project that doesn't have any. In the open source world, there are a lot of technologies in use for documentation, which tend to be challenging for either writers (LaTeX, DocBook) or readers (ad-hoc wikis) or both. FLOSS Manuals provides a technical infrastructure that is easy for writers to contribute to (you don't even need to use HTML), and supports documentation structures (books with chapters) that are familiar to readers.
|
|||||||||||