Tech Writing in the Age of Open Source -- reallylinux.com
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
1. THE READER FEEDBACK
One of the most
substantive aspects of collaboration and communication is the
increasingly rich and useful feedback loops that exist in the Open
When your organization
publishes a white paper, marketing document, or user guide, there are
many ways to get almost immediate feedback.
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.
"Content is not king, it sits subservient to the content consumers"
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
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
Best of all, in today's
tech age, the article can undergo improvements during reader
2. THE LIVING DOCUMENT
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
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
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.
"search engines 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
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
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
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
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.
"your organization's website is gaining a huge volume of useful data from 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:
referring websites and what content they link to on your site
Clear view of
Google search terms that link to articles and which ones get most
Big picture of
what the existing reader audience does when they come to the website
painful truth about which articles attract plenty of readers and
which ones don't do diddly
Which articles on
syndicated websites are most popular and why, such as they are being
promoted or linked from a key page
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)
How well a
specific article is doing in terms of linkage from google search
terms, you'll be surprised!
The breadth of
countries accessing the site and which nations are most frequently
looking at certain articles to understand some of the international
How many people
are passing a link of your article around in their emails such as
email referrers in the logs that look like:
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
Timing and timeliness
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
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
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.
"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
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
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" 2nd 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.