Writer ?

Interested in writing articles, reviews etc., but don't know where to publish it ?. Don't worry, software helper provides you the opportunity to publish your articles, reviews etc., in our Writer's Corner Section. If you contribute articles regularly to software helper, you will become one of the Official writers of softwareonlinehelper.blogspot.com Submit your articlesEmail me!
Photobucket If you're looking for more information within or out of this site, you can search Google . Google is the fastest and the most reliable search engine on the net today. Type in the Google search box below, the key words of the information you want like "free mobile software". Add google search box and other specific keywords to get a more relevant search engine results for the information, resources or ideas you are looking for.
Search here
Custom Search

Share This On

Thursday, June 12, 2008

putting the writer back into technical writing

In the introductory piece for Web Ware, I took quite a few potshots at the field of technical writing, damning most technical pieces as being obtuse, jargony, and pretty much useless. I think, my summation of the situation was, "...most technical writing out there bites the big one and there's no sign that the situation is going to get any better in the near future."

Well I'm here to say that when you publish your opinions in the public eye, you had better be prepared to back up your position!

Scant hours after the piece went online, I received a very valid and useful criticism of the article which I wanted to share with all of you. Cyril Vidergar, a documentation writer for a large computer company, wrote me saying, "What would you want to see in software manuals/technical writing to further disassemble the mystery?"

Well, that is a big question of course, and difficult to answer. However, it is absolutely the right question to ask.

After all, it is one thing to complain about the shortcomings of technical writing but quite another to actually set forward a reasonable solution.

I am grateful that Cyril provided the slap in the face which I deserve for only taking on the easy part in my editorial. So thanks Cyril, and here is my best attempt at an answer. (1)

As I see it, the way to produce better documentation is a three part process:

  • recognizing that the customer is king,
  • recognizing (on the part of corporate resource management) that good documentation is as important as good code and that good documentation demands a full time partnership between writers and programmers, and
  • recognizing that technical writing is a teacher/student relationship.

I'll discuss these three aspects in just a moment. But first a small but important disclaimer.

Like any art form (and writing, be it the writing novels or the writing of specs for a large software application is certainly an art form) there is no "right" way to create. So, read on. But read on with this thought in the back of your mind: "This is what Selena Sol has learned while writing technical pieces. Many of the observations may not be appropriate for me!"

More importantly, if you are writing technical pieces, take time to really work through this problem for yourself. Define your own voice and your own style. The crucial thing is that you take time to make your writing better. After all, it is not enough to write code that works. You must also write code that is easy to modify later; by you, or by the next programmer filling your cubicle and code which is easy to use for the user. Take time to add knowledge to our computer culture, not noise.

You might even try writing down your own observations about technical writing and publishing them on the web like I have done so that we as a community can learn from each other's experiences.

But let's get on to the argument.

The Customer is King

The success of software is not about bug-free code. Take Microsoft Office '97 for example, buggy as hell, but everybody's got a copy

Neither is the success of software about the production of the most advanced and powerful algorithms or the utilization of the most cutting-edge user interface philosophies. How about Windows 3.1? A behemoth, but still installed on PC's from Cambodia to Calistoga.

Bug free design and cutting edge algorithms are things software engineers care about. But they have very little to do with the success of software.

The true success of software, is based on the relationship you build with the customer. This relationship is built upon five factors and if you get an "A" for all five of these factors, you have an application which solves problems for people, making their lives easier and their work more efficient. You may also make some money in the process.

NOTE: Documenting your code and documenting your product can be seen as one in the same. In the case of documenting your code, you can think of your customers as all the programmers who must build upon, maintain, and modify your code after it has been written (this could include you yourself).

Specifically, as a software producer, you must provide the customer with:

  • a software package they can afford.
  • the functionality they require (and nothing more).
  • an easy to use, invisible interface.
  • answers to their questions.
  • steady improvement based on their feedback.

In this article, we will mainly focus upon the fourth factor, answering the customer's questions. But, why should we give a damn about customers with their strange demands, irrational tastes, and limited knowledge?

The reason that we should care is because the ultimate goal of writing software is not to show off your knowledge of arcane and complex algorithms. And, truthfully, though you may not want to hear this, the ultimate goal of software is not to create bug free code. Bugs are the unavoidable result of software and fine tuning is an endless process (which very often introduces new bugs).

The reason that we should care about customers is because software is created for them, not for us. Software is created to solve their problems; problems they define and redefine.

This is a crucial mind set which must be understood by the people who write code and the people who write about code. The customer is king. If an algorithm does not support the customer, it should be removed. If documentation does not support the customer it should be rewritten.

Putting Resources Where They Belong

So how do most companies and software engineers go about writing or rewriting documentation. Well, the sad fact is that most companies don't. My favorite quote on the topic from my experiences in Silicon Valley is, "Well, we will deal with documentation if we have time at the end." No joke. Someone really said this to me.

The fact is that most software companies relegate documentation to the back of the bus.

Of course it is easy to see why. The software industry is vicious. The only way to stay alive and to make money is to be first to market and first to innovate. That doesn't leave much time for real, quality documentation. The goal is to crank out working, or semi-working code as fast as humanly possible in order to beat the other twelve companies at your heels. If any stage in the process of software development (design, development, quality assurance, documentation, marketing, sales) is going to be shaved out of the picture, it is going to be documentation.

Further, even when companies allot time for documentation, they very often use the programmers themselves as the primary authors. Sometimes this can be great. But most often, the programmer is the worst person you can get to write documentation. For one, programmers are not necessarily good writers. Like we said before, technical writing is an art form. The programmer may be a brilliant logician, but that has no bearing on whether or not they can teach.

Further, the programmer is typically biased about and probably fed up with the code already. That is, by the end of the development cycle, the programmer knows the code like the back of her hand and what may not be obvious to the average Joe is certainly obvious to the programmer. Thus, the programmer will usually not give adequate explanations of difficult ideas because to them, they are simple ones because they are so familiar. The programmer will have no perspective.

The result of all this of course, is that documentation organizations are last on the list of high priority employees or projects and that development is king and documentation is...well...last minute.

This, of course, is a very serious problem. Bad documentation is not just bad for the company or the individual producing it. Shoddy documentation has profound ramifications on the development of cyberspace, and thus, is bad for everyone.

Every "newbie" that is bored, intimidated, or frustrated is one more newbie that supports the stereotype that computers are hard to use and not our friends. The longer that stereotype pervades, the longer it will take to really apply the power of computers to the betterment of human society.

Granted, this is a pretty abstract idea in the middle of a piece on technical writing, but it is one which must be in the back of the mind of every software engineer. Progress must not occur for the sake of progress, but for the sake of making life better. We are all responsible for this goal in our own little, but important ways.

Documentation is more than simply a crucial way to support the customer. Documentation is a crucial foundation upon which we will build the information revolution. Documentation is about generating knowledge and meaning, not about data and information. Documentation MUST have quality.

More specifically, companies must invest in documentation departments which contain both technically- oriented staff as well as English and psychology majors, maybe even a graphics designer or two. Documentation must be given a high priority and the ability to integrate closely with engineering during all phases of software development from the definition of requirements to the bug testing of quality assurance.

Writing as Teaching

Of course, once we have a group of writers working on documentation, we must make sure that they are comfortable with the medium they will be working in. Technical writing, as any art form, has many quirks which separate it from other forms of writing such as poetry, novels, short stories or news articles. Technical writing has its own styles, tools, and tricks which make it a unique process.

So, how can we help support the customer with our documentation? How do we answer their questions about using our products? How do we go about actually doing technical writing?

Let's get one thing straight. Technical writing is not a speaker/audience relationship. It is a teacher/student relationship. Technical writing is about teaching people how to use your product and your code. This relationship comes with a few aspects which we should understand if you are to write successful docs.

Understanding the Characteristics of a Student

The first thing that we need to understand before we start writing about some technical issue is that our reader has a few general, stereotypical qualities which we would do well to incorporate into our documentation strategy. The following list reviews some of the characteristics which will greatly direct your writing.

* Students think that what you have to say is boring
  • o Incorporate pictures into your text. If it looks fun, it is fun.

* Students are intimidated by what you have to say
  • You may be extremely familiar with your product, class library, or code base, but that is because you've been working with it for the last few months. Remember that your reader is probably coming at this for the first time.
  • Tell some jokes. Get things off on the right foot. Make the reader feel as if you appreciate the struggle she has agreed to undertake.
  • Use lots of metaphors to explain things. It is likely that the ideas and theories you want to get across correspond to some daily activity that your reader can instantly feel empathetic with.
* Students are unfamiliar with terminology

  • For goodness sakes, make sure to include more description than seems reasonable to you. The advanced reader can skim through it and the beginning reader cannot live without it.
  • Make sure you leave enough time to compile a good index, table of contents and glossary. If you've been a reader of technical documentation you'll know that these "extras" are sometimes the most utilized resources. Nevertheless, most authors skim through them at the last minute before printing.
* Students are insightful, give them a way to send feedback

* Students learn by doing.

  • Only in theory do people learn by theory. In reality they learn by example and participation. Make sure to give them a lot of code to work through. Include the theory in between the lines. Sneak it in so they don't realize they are learning abstract concepts.
* Students have a problem
  • Your readers did not pick up the documentation to learn about the product. They picked it up because they needed to do something with the product. Thus, make your examples useful. Make them cut and paste problem solutions. Takes some time to predict the types of things that your customers will be doing with your code and solve those problems as examples.

Style Guidelines

Once you have developed a positive relationship with the reader, you have fought most of the battle. However, there are still some things which you can do in order to make the teaching process even more smooth. Specifically, you can develop clear standards which make reading through the documentation easier.

Let's take a look at an actual bit of documented code to see what types of standards can be applied.

* Indented comments

Of course, there is a huge body of literature regarding technical writing at your disposal. I suggest that you supplement this piece by taking some time to go to your local library and looking for some good stuff.

The Power of Social Shopping Networks

Looking for ways to get people talking about your products? The new social shopping trend can help you build buzz.

With the vast majority of Americans researching products on the internet before they purchase them in stores or on the web, it’s no surprise that a whole new form of shopping is emerging. “Social shopping” is the intriguing offspring of social networking and online shopping, and it can offer your growing business just the marketing leg up it needs.

Unlike the many retail sites that display products for sale, many increasingly popular social shopping sites (some still in beta testing stages) consist of product listings from site users who recommend their favorites, often with a strong emphasis on what’s hot, new and exciting. And insiders know that listing their own products on the right social shopping sites can build buzz that leads to sales.

This accessible form of word-of-mouth marketing offers a wealth of opportunities for entrepreneurs with limited budgets. To help you navigate these new waters, let’s take a look at why and how social shopping works.

1. Online research leads to sales. Almost 90 percent of respondents to a BIGresearch “Consumer Intentions and Actions” survey conducted in June 2006 said they occasionally or regularly research products online before buying them in a store. When it comes to online purchasing, a study released by Yahoo! and OMD found that nearly three-quarters of the people surveyed use trusted, familiar websites when purchasing online, and the majority (54 percent) say the internet is their most trusted shopping information source. So no matter whether you sell exclusively online, through a brick-and-mortar store or both, influencing online shoppers can have a profound effect on sales.

2. Peer-to-peer recommendations deliver credibility. Social shopping websites allow for word-of-mouth marketing at its best. The internet empowers consumers and accelerates the flow of information. Product recommendations that come from peers may be more trusted, so site visitors may return more often and be more likely to spread the good word and purchase the products they learn about on the sites. Social shopping sites reflect users’ personal tastes and allow for online conversation. Visitors can learn what’s popular, get shopping ideas and follow links to products they wouldn’t necessarily find on their own.

3. Sites have distinct personalities. Here’s a sampling of the hottest social shopping sites.

  • ThisNext.com: Users can browse recommended products, add them to their wish lists, recommend or find out where to buy them, and create themed lists of their own.
  • Crowdstorm.com: This site measures the buzz around products based on user recommendations. Popular items go to the top of the list.
  • Kaboodle.com: Users create wish lists with photos and links to products for sale online. It’s easy to post a summary of anything found on the internet.
  • Stylehive.com: This is the hot site for women’s fashions and interests.
  • Wists.com: Users tend to focus on interesting new products and share links to the ones they want to buy.

4. Social shopping sites are An open door for entrepreneurs. Right now, any business owner can use them to build positive word-of-mouth that leads to sales. But you’d better move quickly. Some sites are testing free-use models as they build traffic and will likely adopt paid structures as they reach critical mass, perhaps through revenue generated by marketing agreements with vendors and retailers or by selling the trend information generated by users.

As with any marketing campaign, your first step is to get to know the media. Bookmark your favorite social shopping sites and learn how they work. Test the waters by posting one or two products with their URLs, taking special care to send your click-throughs to specialized landing pages so you can measure your results. Then have fun and stay active--and keep your postings interesting by sharing products others will want to buzz about.

Kim T. Gordon, author ofMaximum Marketing, Minimum Dollars: The Top 50 Ways to Grow Your Small Business. Her new e-book, Big Marketing Ideas for Small Budgets, is available exclusively from Entrepreneur atwww.smallbizbooks.com.

Link Exchange With Me

If you want to link exchange with me, add my blog into your site and drop me a comment. I will do the same immediately. Happy Exchange :)
Add to Google
PhotobucketPhotobucketNew, unique and user-friendly software solutionsFind the software you're looking for,the most comprehensive source for free-to-try software downloads.Free Internet marketing resources, web site development tutorials, ecommerce strategies & software solutions. Shopping cart reviews & affiliate marketing guides & articles, plus search engine marketing resources & tools. Submit Your Site To The Web's Top 50 Search Engines for Free!ExactSeek - Relevant Search Blog Search: The Source for Blogsfree search engine website submission top optimization Software Top Blogs Technology blogs Software blog directory Fantasy blogs Back Link Site Website Traffic Tracker Subscribe in a reader

Add to Google Reader or Homepage

Add to Plusmo

Subscribe in Bloglines

Add to My AOL

Add to Webwag

Technorati Profile Add to Technorati Favorites

© Make money online | Watch online free videos