Technical Writers and Open Source Projects
She posted her question on the Eclipse Technical Writer Yahoo group asking whether writers were open-sourcing their content. The discussion was limited in scope and more technical than I was first considering for my own presentation, but it opened up a new area for me to consider. I knew that my audience at the NJCEA conference was concerned with literature and essays. Still, I teach in the graduate program in Professional Technical Communications at NJIT, so technical writing is something for me to consider.
If you have an interest in this tech writer side of things, you can read their discussions on the Yahoo group site, but I have reproduced below Virginia's summary that she sent me for any of you that follow (as Tim does) this side of the discussion. Geek warning: this is more tech than usual for this blog, but at least take a look at Q&A #13 below. (Ken)
At XAware, our help is currently compiled using AuthorIT and delivered as output .html and .xml files and is not specifically delivered as source content that users can then modify and compile on their own. Users can make modifications to the output .html and .xml files and that updated content will load (if done properly) from the help menu. Those content changes can be contributed back to the project for everyone's benefit. This process is documented in the XAware wiki for contributing code (see http://www.xaware.org/).
Modifying the output help files will result, however, in a mismatch between that updated content shared in the community and the content management system we use to produce new content unless the author alerts the XAware team who can then make the changes and push it back out to the community.
It may not be the perfect solution, but it is what we have for the time being. We wanted to know if other writers were faced with the same situation.
1. First, tell us a little about what your open source project does and how you got involved with the project.
<JS> My employer publishes the "Enthought Tool Suite" <http://code.enthought.com/ets/>, which is a collection of Python packages that we use for building scientific applications.
<JW> OpenOffice.org (OOo) is a full-featured office suite: word processor, spreadsheet, presentations, vector drawing, equation editor, and database. All user documentation (other than the help files included with the program) is produced by volunteers, members of the OOo community.
<VO> The company I work for, XAware <xaware.org>, produces and delivers an open source composite data services product, which provides real-time data integration services.
... and for part two of the question, "how you got involved with the project":
<JS> I've worked for Enthought for over 4 years. One of the factors that attracted me to the position was the company's attitude towards open source.
<JW> I got involved 5 years ago when the project was fairly new and no user documentation existed, other than some poorly-written and frequently incorrect help files. I had recently retired from a technical editing career, so I wrote and self-published a book about the word-processor component, OOo Writer. Soon after that, I was asked by a group of volunteers to act as lead editor for a user guide they were writing. This group (OOoAuthors) works on a separate website from the "official" OOo project and makes its products available to the official project.
<VO> I got involved almost 6 years ago when the project was still in the University of Colorado, Colorado Springs Incubator and they had some minimally useful technical documentation. I started as a full-time employee in 2002 and have been working for them since. XAware recently converted their commercial product to open source, so it's been an interesting transition.
2. How many writers do you have working on the project?
<JS> Only one person officially known as a 'writer', but 5 others who contribute content
<JW> Don't know; it varies a lot as volunteers come and go. OOoAuthors currently has perhaps half a dozen people active at any given time, though in the past we had a lot more active members. The "official" project may have more members, but few seem to be actively producing documentation.
<VO> Only one person offically tasked with the writing, but others on the development team contribute to the wiki content.
3. What kinds of documentation do the writer(s) deliver with the product and in what format (User’s Guides in PDF, help systems as .chm, etc.)?
<JS> Most User Guides are in PDF, but one is in HTML. API docs are in HTML. Since this project consists mainly of libraries, there are no applications that have online help.
<JW> The online help (not produced by our group) is in HTML.
<VO> User's Guide in PDF (FrameMaker), the help system is Eclipse-based help (which is its own challenge! AuthorIT) delivered in the product, flash tutorials (Captivate) hosted on the xaware.org web site, cheat sheets (XML) built into the product, executable examples (BizDocument, BizComponent, and BizDriver files with dynamically loaded help and Derby databases) built into the product, training (FrameMaker, plus Hypersonic databases) delivered separately, and Wiki pages (WikiMedia).
4. Have you implemented the use of wikis and what kind of content has been migrated to those wikis?
<JS> The project has a wiki that is integrated with the issue tracking system and source control system. Most of content on the wiki is volatile, such as installation and build instructions, or "raw" content contributed by developers, which may be incorporated into more formal documentation at a later date. On the other hand, the wiki has the capability to display files that are checked into the source control system, so some formal documentation is also available on the wiki.
<JW> The OOo project has a documentation wiki, which includes FAQs, how-to's [sic], and tutorials in addition to the user guides produced by OOoAuthors.
<VO> Yes, we have wikis and up to now, the content there is primarily written by XAware employees. The wikis include FAQs, some how-to material supporting the use of XAware, information for new XAware developers who may contribute to the project, and instructions to add the Designer to third-party applications.
5. Have you implemented any animated or flash content and for what purpose (to demonstrate feature usage, etc.)?
<JS> No. One developer has created some demos using Camtasia, which he hosts on his own server.
<JW> No.
<VO> Yes, we have used Captivate to generate some demonstrations of how to use the design tool to create web services, to publish web services, and more. We are adding to the list of tutorials all the time. Each is hosted on the xaware.org site.
6. Do you produce and deliver e-learning?
<JS> Not for this project.
<JW> No, but some third parties do.
<VO> No, but we do produce training, which is instructor-led.
7. How is the documentation delivered (i.e., pushed to a web site, included with the product, etc.)?
<JS> The primary means of publication is delivery with the project. However, it is also made available on a static web site, and in some cases, on the wiki.
<JW> The documentation produced by the volunteer writers is not delivered with the product, but it is made available on the official project's website and the OOoAuthors website. It is provided in ODT (OpenDocument Text) and PDF forms, and on the OOo wiki. Friends of OpenDocument Inc, an Australian organisation, publishes printed books from the PDFs; these are sold through Lulu.com.
<VO> The primary amount of supporting documentation is delivered with the product, as cheat sheets, help, supporting examples, and dynamically loaded help. The User's Guide (PDF) is delivered to the xaware.org web site, where the wikis and tutorials are also hosted. This is intended to reduce the size of the download and provide the type of content the user will expect where they expect to encounter it. Specifically, tutorials on the web site so they can be viewed in a browser (and stopped or re-started, that kind of thing) and help in the product to support pressing F1.
8. What project documentation is written and delivered to users by people who are not technical writers?
<JS> It depends on the component. Some of the tools included in the Enthought Tool Suite are coded by people who are not employed by Enthought. Those tools are more likely to have developer- or user-written documentation. I focus on tools coded by Enthought employees.
<JW> Many of the volunteers do not have a technical writing background.
<VO> So far, almost all of it is written and delivered by a Technical Writer (except for the wiki content, which the entire product team contributes to).
9. What products do you use to deliver the documentation (i.e., FrameMaker to DITA, AuthorIT to HTML help, etc.)?
<JS> I write PDF documentation using Word, but convert it to PDF using OpenOffice.org Writer (to satisfy Debian packaging requirements). The documentation that has been written by others is written in ReStructured Text, and converted to HTML or PDF. API documentation is extracted from Python documentation comments and formatted as HTML using our own tool called "endo". This could also be done using "epydoc". When I write online help (using RoboHelp) for the proprietary products we create for clients, I maintain a separate help project for the features that are provided by the open source tools, and I include that project in the "master" help system for the client product. I include the source files for that help project in the open source repository, along with CHM and RoboHelp WebHelp outputs. AFAIK, no one has ever used this, but it's available on the principle that documentation for open source code should also be open source.
<JW> All documentation from our group is produced using the product itself, OpenOffice.org. OOo can export to PDF and to MediaWiki, among other formats.
<VO> The User's Guide is done in FrameMaker as are the training materials (we use single source content modules where possible). The help is produced from AuthorIT with a SQL Server database back-end and delivered as Eclipse-based help (which requires manual changes). The tutorials are done in Captivate. The supporting examples are built with our product and use a Derby database (also open source). The cheat sheets are done in a text editor as they are XML files.
10. Does your writing team integrate a content management system into the process and if so, which one do you use?
<JS> No.
<JW> Plone.
<VO> AuthorIT, with a SQL Server database back-end, and single sourced FrameMaker content files.
11. Does the writing team deliver the content source to users but also allow users to compile or transform it into other formats?
… if so, what value do you believe is added for the user?
<JS> Yes. The documentation is also "open source".
<JW> Yes, the content source is made available for users to download and modify as they choose.
<VO> Not yet.
... and for part two of the question, "if so, what value do you believe is added for the user?":
<JS> Same value as for open source code.
<JW> Consultants, teachers, others can easily modify to suit their needs, for example by adding their own examples and exercises, selecting specific parts of the user guides and producing another document, localising for a different country or a different variety of English, or translating into another language.
<VO> Some development work is occurring now that will let users contribute their own help when they contribute new components, but we currently have no plans to open source the content even though we acknowledge it might be a good idea down the road.
12. Is the content internationalized, and if so, to how many languages,
<JS> No.
<JW> Don't know. The Creative Commons license allows reuse and modification without notifying us. We don't attempt to control or coordinate translation or localisation. Some of the original source documents are in German or another language, though many originate in English. The user interface of OOo itself is translated into over 40 languages.
<VO> Not yet.
and using what process?
<JW> Volunteer translators. I don't know what process or tools they use.
<VO> AuthorIT's support for translation libraries will help us do this later, but we don't do this now. The product is not localized yet either.
13. How has open source changed your writing practices overall?
<JS> Working on open source has affected me less than simply being a lone tech writer. Because I need to collaborate on documentation with non-techwriters, I choose tools and processes that are accessible to them. This is true whether I am collaborating with coworkers on a client project, or with outside developers or users on an open source project.
<JW> Working with volunteers has required more mentoring, leadership (not management), negotiation, and editing than when working with staff or contract writers. I've enjoyed the opportunity to write in "international English" and work with a talented group of people, many of whom do not have English as a first language. Balancing the varied writing styles of the volunteers with a need for some consistency in results has been challenging, and has reinforced my opinion that many things some editors obsess over are (and should be) far down on my priority list for getting usable documentation published.
<VO> Because the methods users currently use to access supporting content have changed so drastically with Eclipse plug-ins, I am (finally!) able to consider useful ways of presenting user- and task-centric content to the user in an interactive way. No longer is the divide between what the user is doing on the screen, and the help they need so wide - and the gap will close even further with the development of Eclipse and supporting products. So, while some users still seem to want a PDF they can print and study, most users are not willing to spend that amount of time. Instead, these users want and need useful, specific support for what they are trying to do right now. It has opened up the channels of user support and initiated writing a lot of different types of supporting content, which I believe would be difficult to manage without our content system. While we don't currently deliver our content as source the user can contribute to and compile, that day may come.
Other Resources
Lately, I've joined the Content Wrangler's community and found the discussions and articles there to be very timely.
Comments
No comments