A Techie Tech Writer Blog

Now in its fourth year, Google Summer of Code supports students in writing code for participating open-source projects, which provide mentors to help guide the students' work. Thanks to Google's sponsorship, the students receive a stipend (making this a summer job), and mentors receive a nominal compensation for their time.

From the GSoC FAQ:

What are the goals of this program?

Google Summer of Code has several goals:

• Get more open source code created and released for the benefit of all;


• Inspire young developers to begin participating in open source development;


• Help open source projects identify and bring in new developers and committers;


• Provide students in Computer Science and related fields the opportunity to do work related to their academic pursuits (think "flip bits, not burgers");


• Give students more exposure to real-world software development scenarios (e.g., distributed development, software licensing questions, mailing-list etiquette).

If you substitute code/documentation, developers/tech writers, Computer Science/Technical Communication, I think it's fairly obvious that the same benefits could apply to Tech Comm students writing documentation for open source projects.

Members of the user experience community have started an analogous effort called Season of Usability. It's time to do the same for technical communication in open source.

The February 2008 issue of Technical Communication included an article by Dave Yeats on "The Role for Technical Communicators in Open-source Software Development". (You can read it online if you are an STC member.) He gives an excellent explanation and history of the open-source movement, and describes why it is not quite as user-centered as it claims to be. He argues that the best value that technical communicators can offer to open-source projects is not more documentation, but user-advocacy:

Rather than offering to write procedural information for individual projects, technical communicators could use their abilities in user analysis to help developers better understand their target audience and the importance of usability in software. While documentation may offer workarounds and help users navigate unwieldy interfaces, open source would benefit even more if those interfaces were made more intuitive so that the documentation wasn't necessary.

I agree that would be great. The trouble is, I don't see technical communicators lining up in droves to participate in open-source projects at all. I've noted the few I know about.

On the other hand, technical communication students need projects, and they need work products to add to their portfolios if they hope to get a job in this field. Yeats's article mentions the Open Source Development and Documentation Project at Purdue University, which integrates open-source software into technical communication courses. That's cool. (Unfortunately, their website appears to be down as I write this.) However, what if your institution doesn't have program like this? What can a student or instructor do on their own?

That's why I think there is a need for a "Summer of Doc". Or, a "Season of Doc", because it doesn't have to be in the summer, and it doesn't have to be just three months. The word geek in me wants to call it "Period of Doc", just for the cheap punctuation pun, but the user advocate recognizes that that won't make sense to many people.

What do you think? Anybody want to help?

Who are some professional technical writers who are working on open-source projects?

Here are some that I know of:

• Gary Schnabl and Jean Hollis Weber are the current and emeritus editors, respectively, for the OOoAuthors project.


• Tom Johnson has created a Quick Start Guide for WordPress.


• Anne Gentle and Todd Kelsey are working on editing and organizing documentation for the XO laptop as part of the One Laptop Per Child project.


• David Cramer contributes patches for the DocBook toolchain.

If we include people who write books or articles about open-source software, the field is much broader. Most of the O'Reilly catalog falls into this category, and plenty of other publishers publish books and magazines about open-source software as well. It's not always clear who is a professional writer vs. a subject-matter-expert who writes. (And is there a difference as long as you get paid for writing? What if you get published but don't get paid?). However, my interest is in encouraging professional technical writers to get involved in open-source documentation, so I'm specifically looking for examples of tech writers doing this.

Who else? Toot your own horn, or the horns of your friends and colleagues. Please!

I'm just back from the Texas Open Source Symposium in San Angelo. There were about 50 people who showed up, from such diverse places as Dallas, Houston, Laredo, Brownwood, and Grandview. It seemed to me that my talk went well. Besides positive comments people made to my face, I also overheard one positive comment from one attendee to another; so somebody liked it :-)

I will post my slides somewhere. If not on the TOSS site, then here. I tried to follow the Beyond Bullet Points method, so most of the meat is in the notes pages.

Here are a bunch of links that I wrote down through the course of the conference:

• Texas Ubuntu LoCo


• Ubuntu LoCo for Austin


• Parrot, a virtual machine for Perl 6, Python, Ruby, and many other dynamic languages


• LOLCODE, a programming language for lolcats


• TopMod, a 3-D modeling system written in Qt


• Libre Graphics Meeting, a conference about FOSS graphics tools, some of which I hadn't heard of before:
  
  
  
  • Scenari, a suite for creating publishing chains to produce multimedia documents. I'm not sure that this means yet, but it looks interesting.
  
  
  • Scribus, a desktop publishing application. I'd vaguely heard of it, but never mentally cataloged it under "open source alternative to Quark/InDesign.
  
  
  • Open Clip Art Library
  
  
  • Krita, a painting and image editing application for KOffice
  
  
  • Raw Studio, a converter for raw image files
  
  
  • Hugin, a panorama photo stitcher
  
  
  • sK1, vector graphics editor
  
  


• John Wohn, spoke on Making Money by Giving Things Away: Open Source as a Business Model for Technology Companies


• Digital Resources Workbench, a digital humanities project environment from Texas A&M.


• WearPython, Python logo clothes and accessories

Did a bit more searching for open-source/cheap help authoring tools (HATs), and turned up info from some of the leaders in techwriting for open source. Jean Weber's site has a somewhat outdated list of HATs, but still yielded one I hadn't found before. Bruce Byfield wrote an article a few years ago about the state of FOSS HATs. Bruce mentions a couple more shareware HATs, and provides details about HelpMaker.

There are lots and lots of shareware-ish HATs out there, especially if all you want is HTMLHelp output. There are also lots in the $100-$300 price range, which I haven't listed here. Once again, I haven't tried any of these tools, so I don't endorse or vouch for them.

• HelpScribble: Produces WinHelp, HTMLHelp, PDF, and HTML (frame-based) help, with TOC and index. $99.


• QuickHelp: Another HAT that runs on Linux! Uses its own format and Viewer software to display the same help on Mac, Windows, and Linux. Supports TOC, index, and and full text search. This might be a good choice if you require a cross-platform solution that is neither browser-based nor toolkit-specific, and don't require open source purity. $50.


• Fly Help: Supports CHM, browser-based help, and PDA-based HTML. $99.95.


• Easy CHM: HTMLHelp only. Can auto-generate a TOC and index based on parsing the HTML tags. $79.


• PowerCHM: HTMLHelp only. $39.95.


• Help Development Studio: WinHelp, HTMLHelp, browser-based help. $94.95. The same company also makes HelpSmith, which adds printed manuals to the mix, for $120. Note I said printed, not PDF; it sends the output straight to your printer.

By the way, the new version of the HelpMaker website is now up.

I'm always on the lookout for resources to suggest when engineers ask for help with their writing.

My first recommendation for them is the same as my first recommendation for anyone who wants to improve their writing: Style: The Basics of Clarity and Grace, by Joseph Williams, my former professor at University of Chicago. He has other variations on this title, with similar content, but this one is the shortest and least textbookish.

Another book I like is A Guide to Writing as an Engineer, by David Beer, which talks about writing in terms that engineers can relate to.

I recently came across a couple of online resources (thanks to Laura Ricci):

• Rhetoric for Engineers. There is even a Rhetoric for Engineers mailing list.


• Writing Guidelines for Engineering and Science Students

Any other suggestions?

I bought an XO laptop through the Give One Get One program, and gave it to my brother's kids for Christmas. Recently, my brother took a business trip to Thailand, and brought back this clipping of an article about the kids who've gotten XO laptops there:


The full article is online at the Bangkok Post, but you must register to read it. To respect their copyright, I've scanned only the photo and headline.

The article provides some interesting data about how the One Laptop Per Child program works in practice in a developing country:

School director Sukhon Ngamsanong said the Internet lies at the heart of the OLPC project. He suggested the internet access should be high speed, otherwise the students would become fed up, as he has experienced at his school.

"It should be worked out whether the internet expense will be borne by the government or the school because the project targets small schools, which may not be able to afford it. The monthly internet bill of 800 baht is a big burden for us."

Computer teacher Petcharat Chiangda said five of the 37 free laptops went to teachers. In the past three months, 16 machines have been repaired, and five are out of order after students dropped them, breaking the screens.

Hmm. Of the laptops in the hands of children, 65% have been broken, 15% irreparably. As rugged as the XOs seem, maybe they are not quite rugged enough.

And, by the way, 800 baht is about US$25.

If you want to author in Word to produce HTML Help, you might be interested in helping to beta-test ZenHelp. ZenHelp works with Office 2000, XP, and 2003 (but not 2007), by adding a toolbar to Word.

Beta testers will get a free full license when it is eventually released. (But the license price appears to be only $9.00!) Email the author (address on the page linked above) for a password to unlock the installer.

Chatting with Edward Spurlock at the Austin STC Networking Lunch yesterday, I realized my readers might be interested in cheap (<$100) help-authoring tools, even if they are not open source. Below are a few links I've collected. I haven't actually used most of these tools, so I make no endorsements.

• HelpMaker: As mentioned previously, this tool is free but not open source. Their website has been replaced by a static page with download links, but a new version of the software is reportedly in the works.


• FAR HTML: More a collection of tools than a HAT. Think Swiss army knife for help developers. $49 single license, or $44 via Amazon.


• HelpBlocks: Closed-source HAT from the author of the open-source cross-platform GUI toolkit wxWidgets. The only HAT I know of that runs on Linux, it produces HTML Help source files; you'll need to separately install and run Microsoft HTML Help Compiler to get CHM files. $70.


• HyperText Studio: Generates both HTML Help and web help. $49.99 for web-only; $99.99 for "Professional Edition" through end of 2008.


• HelpSetMaker: Open source tool for creating online documentation. Generates JavaHelp helpsets, frame-based HTML docs, and LaTeX source files. Uses its own simplified markup language, not HTML. Supports full-text search, but not a keyword index.

Document Freedom Day, on March 26th, is a global day for grassroots action promoting open standards generally, and open document formats specifically. Modeled on Software Freedom Day, DFD encourages local "teams" to plan events promoting open document formats.

Already there are 169 teams signed up from 54 countries across the globe. Many appear to be Linux user groups, and other veterans of Software Freedom Days. I'm especially amused by the teams named "Docu Mentors" from Chennai, India, and "Kaboom" from Campinas, Brazil. And then there's the "Society for Achieving Destiny" from Abuja, Nigeria, whose agenda is much, much broader than just promoting open document formats.

What exactly the teams will do is up to them. Activities might include sponsoring talks, giving away free software CDs, or other means of "achieving destiny". I'm looking forward to seeing what happens.

Hat tip to Jean Hollis Weber.

(P.S.: In trying to upload the DFD banner, I discovered that my (open source) CMS doesn't properly display PNG files. Sigh. Get with the 21st century, Nucleus!)

Registration is now open for the 2008 Texas Open Source Symposium, to be held Saturday, April 26, in San Angelo, Texas, at Angelo State University.

I'm going to be presenting Not a Programmer? Not a Problem! How Anyone Can Contribute to Open Source Projects at 11:00 AM. Unfortunately, that means I'll have to miss the first half of Eric Evans talk on "An Introduction to Mercurial", which is in the other track in the same time slot. I'm especially looking forward to David Morris's talk on Open Source 3D Modeling Software Development with Qt" and John Wohn's "Making Money by Giving Things Away: Open Source as a Business Model for Technology Companies".

Admission is free, thanks to the sponsorship of ASU. Please register anyway, so they know how many folks are coming.

See you in San Angelo!