I'd Rather Be Writing » open source

Real Projects for Entry-Level Writers Trying to Build Their Portfolios

Tom Johnson — Fri, 26 Jun 2009 13:40:52 +0000

Beginning writers trying to break into the field of technical writing face a paradox: almost all jobs require experience, but they can’t get experience without first having a job.

In the past, I’ve recommended that beginning writers create documentation for any open-source project they can find, such as WordPress, Audacity, or projects on SourceForge.net. However, our organization now has about ten open source projects that would provide an ideal opportunity for entry-level writers to gain real experience in technical writing. These projects are located at https://tech.lds.org/wiki.

The open source projects are designed to allow members of the Church of Jesus Christ of Latter-day Saints (aka the Mormons) to participate in some of the technical projects of the Church. However, you don’t need to be Mormon to help out. In fact, not being Mormon may provide a more realistic technical writing experience, as you’ll be working in a world of terms possibly unfamiliar to you.

In contrast to other open source projects, working on the open source projects at the LDS Tech Wiki will allow you to interact with designers, testers, developers, and project managers. You won’t just be writing help documentation for a stagnant application coded long ago. Instead, you’ll be able to create real documentation for a handful of active, interesting projects that you can showcase to employers.

What kind of projects are available? Here’s a page where all the projects are listed. The projects include the following:

You can include any help materials you write for these applications in your portfolio. Trust me that a strong portfolio can trump years of experience as a technical writer. I landed my first job as a technical writer because I had a strong portfolio, which didn’t even include any real technical writing projects. Imagine how persuasive your portfolio would be if you actually had several technical writing projects you could highlight and discuss.

If you’re interested in getting involved, complete the requirements for participation. And then contact Tom Welch, the director in charge of these open source projects. (Alternatively, let me know and I’ll point you in the right direction.)

If you’re interested in learning more about the organization managing all of these open source projects, see Mormon.org, listen to audio at Mormon Radio, watch videos on the Mormon Channel on Youtube, or check out the resources at lds.org.

Blog Sponsors

Why Free Software has poor usability, and how to improve it

Tom Johnson — Mon, 04 Aug 2008 06:07:38 +0000

Why Free Software has poor usability, and how to improve it. See #2.

Systems that Get Better the More People Use Them

Tom Johnson — Fri, 13 Jun 2008 05:17:45 +0000

In Publishing 2.0, Tim O’Reilly says Web 2.0 is “any network effect that makes a system better the more people use it.” Web 2.0 isn’t just user-generated content; it’s harnessing the collective intelligence of your users to make your system better.

O’Reilly’s definition is intriguing because it’s the opposite of the natural law of use. Your car doesn’t get better the more you use it. A music track doesn’t get better if more people listen to it. Your bank account doesn’t improve as more people use it. Your feet don’t get better the more you use them. Very few things actually get better the more you use them. Not Web 2.0. It’s almost paradoxical. The more people who use it, the better it gets.

O’Reilly gives two main examples:

Google. With Google, every time a user makes a link to another site, Google uses that hyperlink to better inform its search algorithm.
Amazon. Borders and Barnes & Noble have the same stock of books, but Amazon integrates user reviews and commentary to add more value to their literary collection. With each review, the site gets more valuable.

O’Reilly also mentioned eBay and Craigslist. With each system, the more people use it, the better it gets. O’Reilly also has interesting research on publishing and digital libraries, but I’ll save that for another post.

The question for technical writers is not how you can enable user-generated content with your help, but how you can make your documentation better as more people use it.

I wish I could say I have lots of cool ideas on how to do this. I don’t, maybe you do — refine search results based on user queries, allow users to comment on topics, sort topics based on popularity of views, enable users to contribute their own topics, configure search results based on topic viewing time, provide user community, yada yada yada.

These ideas aren’t new or particularly interesting. Partly it’s because they’re still so pie in the sky, how- -do-you-even-do-it type features. Next I’ll suggest telepathically downloading hotspots in user-brains to note the kinesthetic, verbal, or auditory preferences of your users based on the lobes that light up.

Yet we’re at a point technically where many of these features exist or are available. Our problem is that most help authors aren’t programmers, and few programmers get jazzed about coding help tools. When’s the last time you saw an open source help authoring tool that was specifically designed to create help systems?

(Okay, I did see one last week — called PHP Manual Creator, but it looked really primitive.)

In contrast, look at the explosion of social networks, blog platforms, video sharing tools, and countless other killer web 2.0 apps. Inevitably, help systems will also migrate more towards O’Reilly’s idea of Web 2.0. But rather than seeing these blow-your-mind-web-2.0-type tools emerge from the help developer community (i.e., all those companies who advertise in Intercom), I think the next-generation tools will come from web developers and designers who create them for another purpose. We’ll simply repurpose them to deliver help content.