Mirko Tobias Schäfer / Assistant Professor
University of Utrecht Department for Media and Culture Studies
Mirko Tobias Schäfer / Assistant Professor
University of Utrecht Department for Media and Culture Studies
RTFM (Read The Fucking Manual) and FAQ (Frequently Asked Questions) are acronyms for the “teach yourself” attitude that has become a crucial aspect of Internet culture.[1]
Often communities and software projects are peeved by simple questions of new users and therefore refer to the documentation in the ReadMe files and the Frequently Asked Questions. In commercial software projects the end user – often considered as PEBKAC (Problem Exists Between Keyboard And Chair) – led to the development of tutorials and simple interfaces. Clippie, the animated paperclip in Windows Word explains the user how to write letters, format texts etc. The latest Adobe Photoshop came with sophisticated video tutorials explaining how to use the program. However, in open source projects the financial and human resources for providing documentation and information for less skilled users are limited. The usage of this software often requires a higher competence in teaching yourself or connecting to a community that is willing to help beginners without a rude RTFM reference. Microlearning could offer a methodology for integrating the user and stimulate the teach yourself process.
With the introduction of the first home computers in the early 1980s, with the Atari 800 XL and the Commodore 64, the computer acquired the status of a teach-yourself technology. Contrary to driving a car, using a machine or working with tools, using the computer was not taught by experienced professionals. Users had to work themselves through handbooks, manuals and detailed descriptions. Often they joined computer clubs, where people met regularly to train and help each other. Knowledge of computer technology and how to use and to write software was developed in these early user communities. A teach-yourself attitude has been established over the years, requiring users to get started by themselves by reading manuals, FAQs and documentations, as well as learning by trial and error.
An asymmetric knowledge on computer usage developed, caused in the gap between connected, knowledge sharing core users and beginners as well as casual users. Graphical user interfaces were supposed to lower the barrier of using the technology. The computer was to become a medium, a medium that would be interactive in the way that the machine would reply to the user and support the process of learning (Kay, 1990, p. 193).
The design and use of interfaces constructed –as Lev Manovich has pointed out– a cultural code, the language of new media (Manovich, 2001). Computer literacy is accomplished not only by interacting with the computer, but also by the possibility to communicate with other users. The computer and its user are not only connected to the Internet but also to a plurality of other users, who can find help and support in user communities or receive tips from friends and colleagues. Although the netiquette stimulates support for so-called newbies, one often struggles with the materials provided to get a basic grip on the software. Asking questions that are answered in the FAQ is an accepted “don’t”. Codes of communication and social skills must be considered when interacting with user communities. The culture of the information society is a culture of participating and interacting in computer mediated communication and adapt to the different habits in various user communities.
Microlearning could help to diminish the gap of asymmetric knowledge, because it suits the very aspects of computer technology and would be easily adaptable for both experienced users and beginners. The methods of Microlearning can be used for developing a practice of knowledge production and distribution that is easy to acquire and can be shared by the heterogeneous communities that are globally connected in the age of Internet. The asymmetric knowledge is not a mere problem of understanding technology but a social challenge, as well. Microlearning could be a way to build information systems that correlate with heterogeneous user groups, different habits and different cultures.
The term microlearning describes a phenomenon of knowledge acquisition in the context of information and communication technology. It describes how people acquire knowledge by learning in small steps and consuming information in small pieces that form a broader and deeper connected knowledge in the long term. This practice often differs from the established learning curricula in schools and universities. The way users learn to work and play with computers is much more related to the practice of microlearning than to the learning processes in education institutions, because they mostly learn without handbooks and don’t follow a formalised methodology or curriculum. In view of these practices, microlearning is perceived as a process of taking up small pieces of information, of portioning knowledge into modules that can be learned separately at any time when access to a learning environment is granted (Gabrielli at al, 2005).
The concept of microlearning theorises how learning in small steps and pieces constitutes a new understanding of education and knowledge and observes how the process of learning unfolds outside established institutions of education (Hug, 2005). Langreiter and Bolka identify microlearning as “ever-increasing fragmentation of both information sources and information units used for learning” (Langreiter; Bolka, 2005).
The aspects of computer technology, the modularity and versatility, stimulate the process of so called microlearning. Instead of reading an entire handbook, the information is consumed as micro-content. Micro-content describes a piece of information that is necessary in a certain situation and therefore has to be retrievable in the right moment. The micro-content, e.g. a posting in a weblog, is self-contained. In order to fit into the overall knowledge structure it has to be connectable with related information and its context.[2] This comes close to the way in which knowledge is acquired and distributed in user communities. Therefore, the term microlearning describes processes that are already part of the knowledge space and the collective intelligence (P. Lévy, 1999).
Fragmentation of complex knowledge into small portions is part of teach-yourself-processes in user communities. A formalised practice could probably be used for improving the development and documentation of open source software projects, which will stimulate and foster the use of the software. Most notably, microlearning has to be realised as a social practice. Rather than a mere way of learning in an e-learning environment, microlearning describes the production and distribution of knowledge in user communities. In these communities, participants are constantly expanding the knowledge by creating micro-content. This practice is based on the current premises of a specific developer’s community. The way a community is deciding to write and access the documentation of software, has influences on the work process and the communication of the group. It determines how new users are integrated and how the software product is communicated to them.
Especially in the field of software development and software acquirement new methods of knowledge production and distribution have emerged. Here the aspects of software and computer technology are intertwined with users and producers. The communication concerning open source software takes place in communities whose members are connected via the Internet. Open source software originates in interdependency with a collective of users and developers (Raymond, 1998). A software proposal is posted online and people who are interested in developing or using it can hook up and collaborate in the development. Eric Raymond differentiates the loose connections, the flat hierarchies, and the dynamic of collaborations and alliances as the bazaar while the metaphor of the cathedral represents the top down organised method of engineering (Raymond, 1998). The open source software developers form the bazaar where anybody can collaborate in the production of software and anybody can use and modify the outcome. Within these communities both new ways of dealing with code (programming), and new ways of making that process visible (documentation), have evolved, that are significantly different from established ways of engineering. They reveal a different approach to the production and distribution of knowledge. Examples would be eXtreme Programming, a method for software development, which tries to help developers and users collaborate. A prototype of the application –or a part of it– is developed very fast and then tested and modified in the process (Wake, 2000). For developing web applications the software company 37signals published guidelines on how to develop and release software using so-called Rapid Web Development (37 Signals, 2006).
Software engineering is different from other forms of building artefacts. With regard to its structure, software is similar to language. People who are interested in learning how to write code and willing to invest the necessary time, can learn to write software by themselves and with the help of online connected communities. For software engineering the classic institutionalised education is not necessary. Everybody who writes software contributes to the resource of already written software and is able to make extensive use of it. Developing a software application does not require the building of a model first; it is possible to contrive immediately in the software development kit or the Integrated Development Environment (IDE). In these aspects programming software is totally different from classic engineering (Reeves, 1992). The labour of software development often takes place in a more playful mindset, which is not necessarily driven by a monetary motivation. And as heterogeneous as the reasons are for writing software, so are the persons doing it (Rieder, Schäfer, 2005). Collaborative software development in online communities can be attractive even to unskilled users, because they are able to make suggestions for the functions an application should include or they can report what problems the use of software causes. The open source project Mozilla, which develops and maintains the Internet browser Firefox, has built a program called Bugzilla as an interface between developers and users. It facilitates the feedback of users and reports problems and errors as well as users needs in functionality and usability.
For the last ten years open source software was generally considered as a hobby of computer freaks. With the popularity of the Internet browser Firefox and the political debates for open source software in public administrations the general opinion is now more balanced. The open source web server Apache dominates over its proprietary competitors and holds a market share of 69% in 2005.[3] Almost every project associated with Web 2.0 is based on open-source software such as development frameworks (like RubyOnRails or Django) or AJAX (Asynchronous Java and XML) libraries (like Dojo, MochiKit or JQuery).
However, the development of graphical interfaces, providing comprehensible documentation, manuals or a knowledge base for teach yourself processes, which respond to the user’s knowledge and experience is difficult even for well-financed enterprises. For small software development communities such as Helma or Django, this seems unachievable. A lot of software projects confront the user with bad documentation, a non-existing support system, and updates that are difficult to find and implement. Technically and socially inexperienced users are easily discouraged by the technical challenge of installation and the rude replies when asking questions that are considered –by the community– as inappropriate. Small software projects without bigger funding often have no documentation manager, no individual who is responsible for keeping track of all the changes and updates and who is able to communicate with the different groups who are involved such as programmers, early adopters, designers, project managers, and end-users. The lack of information design, the often sloppy documentation and the communication in open source software development is rooted more in the aspects of software and the methods of software development than in a lack of social or economic skills. Firstly, the documentation is often neglected as less important in the early stages of production. Secondly, documentation is difficult to handle if a software project is portioned in countless modules that are programmed individually by a large number of programmers, and only assembled in the end. Thirdly, programmers of open source software are quite often their own users and fit the programs to suit their own needs. They develop the software in collaboration with a peer group that shares the same social codes and technical understanding. Finally, the documentation is often written by developers who know their product/application very well and who are unable (or unwilling) to reconstruct the users' course of action. Furthermore, they are often better at writing code than in describing their application.
The developer’s culture has a significant impact upon the code. For someone who has to review the code of others this causes a lot of understanding problems. There does not exist any standardised or formalised way of programming. As language allows the speaker to say something in very different ways, a programmer has countless possibilities to use a programming language. Code is therefore very personal and the outcome of the programmer’s individual style of using a programming language.[4]
The problems at hand are initially caused by the very aspects of software. Software is modular and therefore the program code consists of various modules and different parts that together build the application. In order to improve the software new modules and patches are added. Software is not a coherent and completed artefact, and it is of high complexity.
Secondly the communication of complex software to users is often neglected. Documentation is necessary as a meta-level connecting all parts in a transparent and comprehensible way. This meta-level also has the task of translating the programmer’s very personal way of writing code. The translation of the code from developer to user often fails because of inappropriate information design, undisciplined communication, neglecting of user needs, etc.
Thirdly, the social issue of different groups interacting is multiplying these problems.
Manuals and answers to frequently asked questions (FAQs) are common tools for explaining software to end-users. User forums are used as an interface between developers and users and support the communication of both developers among each other and between users who seek support from experienced users and developers. A review of the tools of different open source software solutions will provide a deeper insight into problems of documentation and information design in open source software. In the end, the general acceptance and usage within different settings, based on the given documentation material, is a key factor for the success and the further development of the application. A choice of different open source software products were reviewed to analyse the quality of documentation, update system, information design and user support.
Beginning with the installation, the available material and sources (documentation, manuals, tutorials, FAQs, mailinglists, forum, etc.) were used and reviewed in order to set up an application and to successfully use it. The selection included software that is used by experienced users and developers such as web development frameworks, which are used for building web applications, software that is used by skilled users such as weblog software and software that is widely used among common users such as an Internet browser. With special regard to Web 2.0 documentation and user support material from the following open source software projects were reviewed (see table of applications).
This selection consists of applications that might seem irrelevant for most users. The Internet browser Firefox could be described as the only exception of open source software that is widely used by common users. But there is an increasing use of software products that facilitate the construction of HTML websites, such as weblog software and wikis. These are very popular among skilled users and do not necessarily require programming skills. Both systems are widely used on the Internet, distributing information and exchanging knowledge. The most popular wiki is probably the free encyclopaedia Wikipedia, which is built from the mediawiki software. Weblogs and wikis are expected to aid learning processes both in e-learning and in software usage and software development. Moreover the selection of open source software products describes means of production of an emerging software-industry that is using open source tools for building individual solutions for their customers. The usability of open source software has an economical impact, too. The easier software designers can apply certain software, the faster they can produce websites, web applications and software solutions.
Currently, documentation is usually split up to one or more of the following tools:
The main weakness of online tutorials, manuals, FAQs, wikis and weblogs is that they are usually not the result of an organised learning-environment including developers, designers and test-groups. The information provided is incoherent, unorganised and incomplete. There is often no formalisation or categorisation of information. One may find information on a certain topic in several places, usually without any additional explanation and connection to related material.
The issue is not adding information; the problem is to find and retrieve appropriate answers and information in a labyrinth of available yet disconnected fragments. The information is provided in small pieces, to use the terminology of microlearning the information is available as micro-content or as a knowledge nugget. Retrieving the necessary piece of information is the matter at hand. Storing information of complex contiguity requires a meta-level that can connect the small pieces of information and allows recognising the context. It is necessary to connect the small pieces of information to a meta-level, which organises them into the appropriate context.
Writing the documentation is as tentative and modular as its developing process.
Besides, documenting software is often neglected by the developers and compensated for later. A coherent and continuous documentation is often not achievable. This is why the micro-content that is produced during the process of development, or added later needs to be linked to a macro-level. Providing the micro-content with meta-information could facilitate the connection to the context. It must be possible to connect the small pieces of information and provide a method of information retrieval that can replace the old-fashioned way of documentation that is still similar to the linearity of handbooks. It is essential to gain knowledge of the macro-context while dealing with its micro aspects.
The problem can’t be solved on a technological level only. It requires a rethinking of methods of storing information and adapting technology to cultural practice and a rethinking of formulating and organizing language to describe action processes. Additionally, social aspects have to be taken into account. The questions that have to be taken into consideration are:
Information systems online are used by a vast number of users. It is impossible to expect a user to read a handbook first for participating in an online project. Although netiquette was a favoured concept in the 90ies and is still visible in the various posting guidelines of countless mailing lists, a guideline would not improve users input to software projects. The tools used for storing and extending the information must meet the cultural practice and should not be a hassle to those who add value to the system by contributing information. Contrary to the coherent group of employees of a company, students of a faculty, or members of a team, the plurality of users is dynamic, heterogeneous, continuously changing and unknown to the maintainers of the system. As Ciborra correctly points out, an information system is only useful if it is able to integrate its users and allow them to implement the system in their context (Ciborra, 2002, 32). A guideline how to fill in information won’t be sufficient as well as the formulation of standards, which are not adopted by users. In software development, technical and social processes are complex and dynamically intertwined.
The common documentation-material as listed above can be replaced by less confusing and time-consuming tools. It seems appropriate to take advantage of cooperative structures (based on a given information design) that build a knowledge data-base, which is easy to access and easy to extend. There are hundreds of different wiki tools, almost all with special features and individual handling of data and content. Choosing the right tool for specific needs may solve a lot of potential problems beforehand. When using several tools, it is indispensable to explain the different objectives and possibilities.
Microlearning offers a terminology and methodology that seems to be useful for open source software development. Following some basic guidelines, developers could support and improve the documentation process. If a certain function requires more information, the developers could build a link to a help library explaining this particular function. This could be perceived as a micro learning step. The information provided would be a micro-content. A collection of such micro-contents could be developed during the first stage of building the software. Meta-tags added to each micro-content would ensure that the various pieces of information are connected retrievable.
If users are looking for help, for information on a certain function, or want to solve a problem, a good information system avoids that the user is working herself through hundreds of postings, FAQs and manuals. Connecting all those pieces of information with a meta-level –which could be realised by tagging information– a search function could direct the user to the necessary piece of information. Adding new information to the system must require the connection to that meta-level. That way a knowledge base will be created that could easily be extended and maintained by users themselves.
The database becomes the central place for storing information; the process of storing and retrieving this information is the key to efficient usage. Since Micro-content tends to get lost without the necessary connections, it is crucial to not only store these knowledge-nuggets, but also to relate it to other information as much as possible, making it visible within different contexts. This leads to well-designed micro-content, readable within different paths or levels of information retrieval. Maintaining the database would entail correcting and improving the stored information by adding or changing tags. Instead of constantly expanding the given documentation material into countless directions, this approach forces the reader/writer to thoroughly re-think the context of the material, shaping it according to its possible connections. Besides, the user stumbles across already familiar bits of knowledge now and then, without getting lost in varying descriptions of the same phenomenon.
Software design is more than the mere development of an application. Creating tools for learning how to use the application is to be recognised as a task of software engineering. Information design essentially deals with basic concepts of data formats, the accessibility of content, the preparation of useful navigation paths and finally with an overall aesthetic idea of what is to be presented. It is definitely a task within the realm of information design to integrate ways for users to interact with a program on the technological level (through RSS feeds or API) as well as the overall question of integrating the user from the earliest possible stage of development. Documentation turns the complexity of code into comprehensible knowledge.
Documentation should become an ongoing process, where participants add micro-content, which enables different paths and combinations of the given material. This makes it easier to find necessary information and turns the time-consuming quest for information into an efficient learning process. Analyzing the learning processes involved with using the aforementioned open-source applications, the whole process turns out to start all over with every single application. Instead, one should be able to adapt from software one already knows. This is primarily a consequence of the lack of standardisation and also caused by the individual communication and programming style of each single developers' community. In the case of the software FCKEditor, the wiki is found under the button "Support" and is basically the documentation. In the case of RubyOnRails the wiki is found under the button "Community" and is a place for user contributions to the documentation. In the case of the project Django the Wiki is found under "Code" and refers to the integrated TRAC-Wiki, which in this case is used as a place for almost everything (from browsing the source-code to linking to tutorials on the web). Obviously, a terminological standardisation across thousands of very different applications serving different communities is impossible to achieve. As illustrated above, it is often hard to adopt learned knowledge and procedures if there is a fundamental difference between various documentations on a basic level. The creation and consumption of micro-content is not time-consuming and can take place between different activities, in breaks or gaps within the daily work. The possibility to get a picture of the material on offer, as well as recent changes or recent news is essential. Highlighting such changes is easy by integrating RSS feeds that keep users posted. Because the documentation of open source software is largely based on contributions by users, they are themselves responsible for making available the documentation in the most comprehensible manner. Almost every community establishes an individual way of making information accessible. This is especially problematic, because these communities have to rely on users to shape, arrange and revise the material. The preconditions to shift the responsibility on to the users are:
New ways of software engineering, participation and adoption require overcoming established views on software documentation. These products are constantly in flux and providing documentation must follow this progression. The cultural practice of writing and distributing software needs an appropriate way of documentation.
Bringing together the collective intelligence of developers, user communities and individual users in order to provide relevant teaching- and documentation-material should be achieved by revisiting tools for documentation and interfaces for user-developer communication. This can be accomplished by the implementation of tools that facilitate both using technology and interacting on a social level. Predefined guidelines may ease the growth of documentation material that has to be reusable, modifiable and readable by machines. Furthermore, the resulting micro-content should be assembled in order to provide micro-learning-steps. Users and developers would add meta-data to each micro-content and weave a web of knowledge that can be consulted and expanded. Since the single user (the one who is actually “learning”) adopts the given material, she is aware of the strengths and weaknesses of this material (with regard to her very individual learning situation). The plurality of users is then able to shape and modify the material.
Allowing the user to extend the documentation by setting links (hyper-textual content), by making notes, that are visible to other users, by changing content and mutually correct or adjust others contributions, and by adding new content which is self-contained, still reusable and modular.
Making it easy for the user to extend the documentation by giving her appropriate guidelines (helping the user to produce micro-content explaining the notion of micro-content as is), by exactly bringing across the different tools and their meaning, making it clear where to ask what kind of questions and where (and how) to extend the given material by restricting the possibilities (e.g., avoid duplicate entries on the same issue) by standardization (if gathering and extending information is standardized across several applications, the user may adapt faster). Limiting the ways in which the given material is presented (it is more efficient to have one Wiki with elaborated information than to have tons of different tutorials and/or manuals with out-dated and isolated information), explain that decision and choose additional tools if required. This will make it easier to find appropriate answers and to maintain the documentation.
Even if the information design does not allow for these possibilities, micro-content should be stored in the most hyper-textual and reusable manner (e.g. using tags). The document structure (semantics) has to be well-defined according to given standards (W3C, microformats) and the content should be machine-readable (through metadata and/or XML-formats like RSS, for example). Moreover, it should be possible to export the documents and read them offline.
Feasible information systems will provide a functioning interface between developers and users. If early adopters are enlisted as soon as possible and assigned responsibilities with regards to documentation material interested persons and potential end-users can participate in the process and improve the documentation according to their needs. Therefore, guidelines for documentation and participation should be published in an early stage of production.
Providing a list of what is not working, where problems are and whether they are going to be solved or not will avoid frustrated users. If developers make clear what the problems in a given application are, they avoid answering complains and questions concerning these problems. It may also stimulate users to participate in problem solving. Receiving help from the plurality of users requires a functioning flow of information within a well maintained information system.
Taking the open source movement to the next level would require getting rid of the PEBKAC and instead to get the user on board of software development. The gap between less skilled users and the advanced ones could probably be diminished by a better co-operation between developers and end-users, facilitated by suitable integration of micro-learning-steps and a dynamic information system. It has become clear that software development is a highly social process that requires a different way of thinking about engineering methodology. Accessible knowledge, that is open for modification and adaptation in an environment that allows users to communicate among each others as well as with the developers, will become inseparable from the programming process. The previously underestimated newbie becomes part of the community and gains knowledge through basic communication techniques. Advanced design and documentation has to meet the challenge of including diverse user-groups at different stages of knowledge and practice. Perceiving software development as rather a social than a technical process leads to different methods of development. Microlearning could stimulate the integration of tools into communication processes in user and developer communities and stimulate the development of dynamic information systems.
37 Signals (2006) Getting Real: The smarter, faster, easier way to build a successful web application, online publication, available from <http://www.37signals.com>
Claudio Ciborra (2002) The Labyrinths of Information. Challenging the Wisdom of
Systems, Oxford: Oxford University Press.
Gabrielli, Silvia; Kimani, Stephen; Catarci, Tiziana (2005) The Design of MicroLearning Experiences: A Research Agenda, online text: <www.microlearning.org/micropapers/MLproc_2005_gabrielli.pdf>
Hug, Theo (2005) Microlearning: A new pedagogical challenge, online text: <http://www.microlearning.org/micropapers/MLproc_2005_hug.pdf>
Kay, Alan (1990) User Interface: A Personal View. In: Laurel, B. ed.: The Art of Human-Computer Interface Design, Reading, Mass.: Addison-Wesley, pp. 191-207.
Langreiter, Christian; Bolka, Andreas (2005) Snips & Spaces: Managing Microlearning, online text: <www.bolka.at/pubs/2005/snips.pdf>
Lévy, Pierre (1999) Collective Intelligence. Mankind's emerging world in cyberspace. Cambridge, Massachusetts: Perseus Books.
Manovich, Lev (2001) The Language of New Media. Cambridge, Massachussetts: MIT Press.
Mathes, Adam (2004) Folksonomies - Cooperative Classification and Communication Through Shared Metadata, online text:
<http://www.adammathes.com/academic/computer-mediated-communication/folksonomies.html>
Reeves, Jack W. (1992) What is Software Design? In C++ Journal, 1992; online: <http://www.bleading-edge.com/Publications/C++Journal/Cpjour2.htm>
Raymond, E. S. (1998) The Cathedral and the Bazaar, First Monday, 3(3),
online text: <http://www.firstmonday.org/issues/issue3_3/raymond/>
Rieder, Bernhard; Schäfer, Mirko Tobias, (2005) Beyond Engineering, online text: <http://procspace.net/berno/files/design.pdf>
[1] For detailed information on these terms, consult the Jargon File, a glossary of hacker slang: http://www.catb.org/~esr/jargon/html/lexicon.html
[2] A good example would be the so called tagging of content online. Users add a tag, a piece of meta information to a picture, a sound file or to text, in order to provide information on the stored information. Tagging promises a more efficient and semantically correct information retrieval, because a plurality of users is providing the taxonomy of content stored online. For an introduction see Mathes, 2004.
[3] Netcraft ServerWatch October 2005, http://www.serverwatch.com/stats/article.php/3554746.
[4] While this is mostly true, object oriented programming (OOP) and programming-languages like Python and Ruby tend to restrict the personal choices. PHP is a good example of a programming language that allows many choices in how to achieve something that offers less structure and regulation.
[5] TRAC: http://trac.edgewall.org/
Date December 2006 Category Publications
with Patrick Kranzlmüller: RTFM! Teach-Yourself Culture in Open Source Software Projects, in Hug, Theo (ed.): Didactics of Microlearning, Berlin, New York: Waxmann, 2007, pp. 324-240.