Tech Writing in the Age of Open Source
by Mark Rais, senior editor ReallyLinux.com

There are four core ways to use open source techniques and technologies to dramatically increase the effectiveness of any organization's tech writing. These techniques can greatly enhance the power of technical writing applied in user guides, marketing materials and software documentation.

When we publish an article at reallylinux, the author is able to immediately gain insights from readers, not only through direct comments, but also indirectly through the thousands of comments and insights on related websites that syndicated or linked to the article.

For example, one of our articles received 2,327 comments within 30 hours:

As a result, we were able to learn from reader feedback, enhance the article, improve the context and create new articles that further explore reader concerns. All within less than three days.

Few things can educate a technical writer more than receiving thousands of comments regarding an article. Even off topic comments shed light on the thinking, the needs, the concerns of the readership.

Content is not king, it sits subservient to the content consumers. In our case that means: the reader. And with the countless web sites and blogs combined with powerful search engines, researching reader feedback has never been easier or faster.

One of my requirements for writers is that they follow an article's life by researching all of the syndications and sites and reading as many reader responses as possible. Every person who responds to an article sheds light on a facet of the article.

As a technical writer, it is essential that you spend time reading your audience's feedback to every article, every time. The easiest way to accomplish this is to become familiar with the key news or syndication websites and visit them when your article rolls out on the web. It is also essential to research your article using search engines like Google, where you can not only identify who has been syndicating the article but also what each of these unique communities are saying in response. Get use to doing a Google search on the full title of your article within 72 hours of release. This gives you the maximum picture of your article's effect on the community at large.

People who love an article, and share comments on various sites, shed light on aspects that are beneficial. This allows the writer to identify key ingredients of success for inclusion in subsequent articles. In some cases, it also helps quickly enhance articles for maximum effectiveness.

Even people who hate an article provide a writer invaluable insights. For instance, they shed light on some fundamental gaps in logic that need to be improved, or gaps in research. Of course, a writer has to be pretty thick skinned to gleen beneficial information from harsh comments. What I learn as an editor is rich and often magnificent. For one thing I learn the hot button topics and each time we publish, we increase our readership and effectiveness because we take time to learn from the previous feedback, even negative feedback. But perhaps even more importantly, the article can be improved through the insights and breadth of commentary and the tech writer grows in effectiveness.

Best of all, in today's tech age, the article can undergo improvements during reader feedback.

2. THE LIVING DOCUMENT
The tools, infrastructure and communication mediums available through the Open Source community are all intended to help expedite development projects. In turn, they also create incredibly effective resources for technical writers.

As a writer, not only do I get lots and lots of reader commentary through the various feedback loops, but the comments are near immediate. We publish an article, it hits the web and syndicates across websites, and within a few hours comments are showing up around the world.

If an author understands this and gets in the habit of watching key syndication websites, many positive things can come about. As I mentioned, the author can immediately update the article in response to concerns or reader thoughts.

I've learned that somethings are just going to be missed in a detailed HOWTO or user guide, even when an author has taken time to review the document, given it to an editor for review, and gone through a final pre-publication check.

No editorial staff can ever compete with or improve upon the thoroughness of the thousands of intelligent eyes of readership.

But perhaps what needs to be most overtly understood is that search engines and the Internet basically take an article and ARCHIVE IT FOR ETERNITY.

This is a very serious issue for technology writers. It becomes even more essential to habitually improve and update your material based on feedback and changes in context. Otherwise your brilliant and exceedingly useful article will show up on reader searches two years later with utterly useless jibberish.

We try to revisit older articles that remain popular. We then run another feedback loop and update several months following publication. This helps ensure we are not screwing readers who will find the article on a search engine and try to use tips or steps that are no longer appropriate. It ensures that we become a respected source of information, which is in essence what every organization desires from their tech writing.

Reader feedback is great, but it is even better when incorporated into UPDATES as a living document. Quality technical documents are always living documents.

3. QUANTITATIVE ANALYSIS
Even if an editor is kind enough to be willing to commission an article through whim alone, a writer needs some quantifiable data to back the premise. Any business or organization that does not have some form of quantitative analysis for their content is missing a big piece of the pie.

Such quantifiable analysis is far easier than you may think, thanks to the use of today's rich web access logs. Thank you guys on the team at the Apache project!

Before I ever sit down to write an article, yes much like this one, I spend a good few hours glossing over the Apache http logs. I need to know my regular readership, I need to understand what people are looking for in terms of information, and I need to write articles that help address these needs.

I write based on real need in a real context for a specific timeframe. The result is obvious. In most cases, I have found that the http web logs can offer wonderfully satisfying data.

There is so much to be gained from reviewing and learning about your Apache web logs that I will write another article just on the topic. For now, believe me when I tell you that your organization's website, or company web presence is gaining a HUGE VOLUME of useful data from those webserver logs.

If you want to know who's doing what with your web content then spend a brief moment with your logs.

I sometimes spend several hours per week reviewing our parsed weblogs. Why? So that, as senior editor I have some evidence of what readers coming to the site desire. When I decide on a new article or HOWTO, it is based on a lot more than just personal qualitative "feel."

What can the Apache httpd logs provide an organization's writer or editor:

1. Understanding of referring websites and what content they link to on your site

2. Clear view of Google search terms that link to articles and which ones get most hits

3. Big picture of what the existing reader audience does when they come to the website

4. Overt, sometimes painful truth about which articles attract plenty of readers and which ones don't do diddly

5. Which articles on syndicated websites are most popular and why, such as they are being promoted or linked from a key page

6. Which articles are picked up by major media outlets, often prior to them appearing (search the logs for media related email threads such as http://webmail.bignewssite.com/, often an indicator that someone from the media came to your site)

7. How well a specific article is doing in terms of linkage from google search terms, you'll be surprised!

8. The breadth of countries accessing the site and which nations are most frequently looking at certain articles to understand some of the international appeal/significance

9. How many people are passing a link of your article around in their emails such as email referrers in the logs that look like: http://us.f50950590905example.mail.yahoo.com/

10. Which articles written ages ago by you or on your site still get hits from key websites, which often gives insight for what updates to make and what future articles need to be written

If I have not yet convinced you that a writer gains a lot of useful insights from a cursory evaluation of the web access logs, then perhaps you don't need quantitative data.

4. NEW AGE OF TECH WRITING
In this new age where an author's writing is instantly available across the world, a global context and perspective is very important. The Open Source models and community can help get better acquainted with this broad perspective. People in the OSS world have been interacting and effectively interrelating with others across national boundaries and cultures for years.

What we can learn from this experience is foundational to the success of an organization in the global market. So, I offer several important tips to ensure your organization's writing remains strong and effective in the new age.

Timing Over Perfection
I have worked for organizations that take so long to release documentation that when the published material gets to the end-user, it's already outdated. And in my view outdated is a polite way to say: worthless. Why this happens can be debated. But in many cases the reason includes an editing cycle so thorough that the audience/purpose of the document succumbs to the monumental desire for perfect English.

Although this emphasis on "exceptional grammatical quality" may be a worthy trait, it is a worthless cause. When there are probably 10,000 BLOGS, a million websites, and one hundred books written about the same technology every month, it is difficult to fathom how perfect grammar can matter.

Timing and timeliness are essential.

If you need a document written for your software project, you don't want an editor who ensures every comma and semi-colon is in the right place, because it could COST THE PROJECT. Timing matters. Believe me, it matters more than ever before. Good editing is a balance between clarity and timeliness.

Active Voice and Other Old Ideology
Let me share how some writers are enamored with the use of active voice. Although it is true that often the active voice can help clarify a point, it is not key in effective writing. Sadly, the active voice is often instilled as the essential ingredient to excellent technology writing. This ideology worked better in the past than today in the new age of information and writing.

In today's world, the sometimes almost religious pursuit of active voice fails in two respects.

The active voice, if used almost exclusively, gets down right tiring. It can indeed help with step by step guides. But, I propose that it's nice to have a voice that is sometimes more personal and personable, even in technical guides.

I have also found that the active voice is a principle restricted in some ways to an American cultural context.

In many countries of the world, a document written exclusively using the active voice is seen as rude. For example, to our audience in Asia it is important that an article is delivered in the third person, because this is seen as a sign of respect. So, an article with a global audience needs to take into account the voice and context and form some type of balance.

The author and actor should not always be present in every step, in every point. Otherwise, the article can be perceived to be arrogant. Believe me, active voice is fun and easy, but can seriously be a negative when going ACROSS CULTURES, when departing from a strictly American audience.

It's better to write in a more modest, more balanced way that can be digested by divergent audiences.

Conclusion
The most effective forms of technical writing are those built upon quantitative analysis, drawing from countless reader feedback comments and web logs, and relying on simplicity and clarity rather than perfect grammar.

When you're looking at a global audience, reading thousands of pages of information per week on the Internet, you need to change the methodology to adapt to and utilize the best models already in existence. Models that are readily available in the Open Source context. Applying many of the techniques and tools of the Open Source world will dramatically increase your technology writing productivity and effectiveness.

Mark Rais is senior editor for reallylinux.com, has written and contributed to five books including "Linux for the Rest of Us" 2^nd Edition, and authored numerous articles now read in over 150 countries. He has provided technical counsel to leaders in Africa, Americas, Asia and Europe. Rais currently spends his time helping promote technology solutions to bridge the divide among poor nations.