The Challenges of Open-Source Documentation and Training

There are at least two important issues that are closely related to the open-source software support questions we raised in part 1 of this look at open-source practicalities: documenting the software and training people to use it. With a traditional, commercially licensed product, documentation is as simple as obtaining a hard copy, a CD or going online to get all the details needed from the software's developer. Or, if something is missing, using support from the vendor to get questions and issues resolved.

Smith, Tom. Open Enterprise, The (2003). Articles>Documentation>Open Source

A Few Thoughts on FOSS Help Authoring Tools

There's a lot of great free and Open Source (FOSS) software out there. But one area in which it's lacking is professional-level help authoring tools. In 2005, Linux.com published an article titled "FOSS help authoring tools falter". And not much seems to have changed in the intervening years.

DMN Communications (2008). Articles>Documentation>Help>Open Source

Full Text Available Documentation, Participatory Citizenship, and the Web: the Potential of Open Systems  

Technical communicators have become increasingly interested in how to 'open up' the documentation process - to encourage workers to participate in developing documentation that closely fits their needs. This goal has led technical communicators to engage in usability testing, user-centered design approaches, and, more recently, open source documentation. Although these approaches have all had some success, there are other ways to encourage the participatory citizenship that is implied in these approaches. One way is through an open systems approach in which workers can consensually modify a given system and add their own contributions to the system.

Spinuzzi, Clay. ACM SIGDOC (2002). Articles>Documentation>Information Design>Open Source

It's Raining Code! (Hallelujah?)

As open-source development options proliferate, CIOs are finding ways to make it work for their organizations.

Lindquist, Christopher. CIO Magazine (2005). Articles>Documentation>Open Source

Open Source Documentation

Collaborative technologies are supplanting traditional channels for product tech support.

Udell, Jon. InfoWorld (2005). Articles>Documentation>Open Source

Getting Tech Writers Involved in FLOSS

I commented that many tech writers aren't interested in doing more tech writing in their spare time, but might be interested if doing so can help them professionally. In particular, folks coming into the field, either out of school or as career changers, need writing samples for their portfolio to show to prospective employers.

Swisher, Janet. Techie Tech Writer Blog, A (2009). Articles>Documentation>Professionalism>Open Source

FLOSS Manuals Sprints to Build Quality Free Documentation

Documentation is one area in which free/libre/open source software (FLOSS) is weakest. A project called FLOSS Manuals is trying to remedy this situation. The idea behind project is to create quality, free documentation for free software.

Nesbitt, Scott. Linux.com (2008). Articles>Documentation>Open Source>Writing

Choosing a License for Sharing Documentation Content

What issues and legalities do we as Technical Communicators or Wiki Administrators need to be aware of as we move towards collaborative authoring projects and so forth, especially when documenting open source software?

Gentle, Anne. Just Write Click (2009). Articles>Documentation>Intellectual Property>Open Source

Documentation Collaboration Service 

Collaboration happens when multiple people work simultaneously towards a common goal. Collaboration software are tools which try to make working together easier and more productive. There are hundreds of methodologies and approaches out there to collaboration. We want to bring the focus on one particular dimension: open vs. structured collaboration.

Live Tech Docs (2009). Articles>Documentation>Content Management>Open Source

Great Documentation Is Key to Open Source Success 

Listen up open source developers, if you want your project to succeed you’re going to have to do more than write great code; you’re going to have to document it, teach new users how it works and provide real-world examples of what you can do with it. That’s the message from Jacob Kaplan-Moss, one of the creators of Django, a very successful open source, Python-based web framework. At least some Django’s success can be attributed to its thorough documentation which is not just reference materials, but also includes tutorials, topical guides and even snippets of design philosophy.

Gilbertson, Scott. Webmonkey (2009). Articles>Documentation>Usability>Open Source