通过

Writing Technical Articles Part 1 - Step up to the plate and share the wealth

  • 项目

I'm a programmer writer for the MSDN Office Developer Center. My job for the last five years is writing how-to articles for developers that appear on the Microsoft Developer Network (MSDN), specifically, Microsoft Office developers. I have a background as a Microsoft Access developer for approximately five years and as telephone support engineer for Access for two years. I also wrote end-user help topics for Access for three years (yes, you can blame me for some of those helps topics that may not have been as clear or helpful as they could have been =[:^) ). 

Based on my experience, I believe that researching and writing developer help articles and software tools and utilities is a great way to help your peers and help yourself as well. Let me explain. Maybe my experiences can inspire you to share what you know with other developers by writing technical articles or creating tools and utilities. There are numerous magazines and other technical publications looking for well-thought out solutions and descriptions. We published lots of third-party articles on the Office Developer Center (https://msdn.microsoft.com/office) on MSDN. And you don't need to be employed as a writer to do this. All you need is a healthy dose of imagination, some patience, and a plan. Note that in my experience I've found that while a narrative-type of article, say one that explains a technology, is good, most developers like to get their hands on something they can play with or something that makes their job easier. That is why, where possible, it is best to write about a tool or utility you've created or to include code samples in your articles that demonstrate a technique or technology. Regardless, I've also found that the most successful articles are those that include examples or code samples that mirror real life situations or tasks that your audience is likely to encounter in their work.
 
My job allows me to play with the features in various Office products in order to create code samples and solutions, and then write about what I find. Being a database application developer in a past life, you can imagine that I like to work within a process. And it may be obvious to most but breaking a project into discrete steps has several advantages. First, you know there is a beginning step and an end step so you have an idea of how to get started, and more importantly, you know when you're done. Second, if you're interrupted, discrete steps allow you to easily determine where you left off and resume the process. You can also troubleshoot more effectively because you can quickly follow the process back to the point where the results deviated from what you expected and use that as a starting point to see what went wrong. Dividing a project into steps also allows you to easily delegate parts of the project to other developers and then re-combine the separate pieces into a whole.

Getting back to the subject, the most important step in the process is to determine what to write about. This information can only come from one place: the customer. If you don't write about issues that are important to your audience, nobody's going to read your work. For some subjects, you can probably get away with relying on your own experiences as a developer. Often, but not always, something that gives you a problem has most likely been a problem for other developers as well. However, you don't necessarily have to have a problem to write a meaningful article. It's a lot of fun to design and build a tool that automates a repetitive task or an otherwise tedious procedure. By documenting your solution, you could very well save other developers a lot of pain. Another great place to come up with ideas is the newsgroups. Monitoring a couple of newsgroups in the areas you are interested in writing about is a great way to see recurrent issues as well as the solutions posted by MVPs and others. There are a number of tools that help you graphically see which newsgroups had the largest number of posts as well as the threads that generated the most activity. For example, Netscan (https://netscan.research.microsoft.com/) is a good tool to use. Note that although newsgroups posts are in the public domain, as a courtesy you should let the person who posted that solution know that you are going to use their material.

Once you have a clear picture of what you want to do, the next step is to create a plan. For my first one or two years as a technical writer, I often skipped this step causing me loads of extra work and many trips down blind alleys. After looking at the customer data, I usually had a hazy idea of what I wanted to do but no clear picture of the end result. I figured that things would come together at the end of the project. Not writing down what I needed to do in a logical sequence of steps prevented me from taking advantage of the things that a well thought out plan provides. For example, it was difficult to anticipate the potential shortcomings and tradeoffs of a particular design. This usually resulted in several false starts and lots of wasted time. In addition, it was easy for me to go off on a tangent and lose my place in the process. Without a written plan, it was also difficult for me to explain the project to other developers or to my management.

The best way to start your plan is to write down as much information about what you hope to achieve as you can and then reverse engineer the design into a series of logical steps. Along the way, you should try to visualize where you might have problems or where you will need to make choices. Say, for example, is it likely that the developers who read your article will prefer one programming language over another? Or is one language a more logical choice for a particular application than another? Would showing sample code in more than one language, such as C# and Visual Basic, be more beneficial to your audience? This type of decision would also showcase your versatility as a developer and build more credibility for you.

It's also a good idea to discuss your plan with another person, perhaps more experienced developer, in order to reveal areas where the plan may need more work or to uncover things that you hadn't though of. For examples of using this type of a stepped approach, read through the excellent walkthroughs and code samples that are included in the help files in Microsoft Visual Studio. Or search for projects that other developers have written about on MSDN(https://search.microsoft.com/search/search.aspx?view=msdn&st=a&c=0&s=1). These can be good templates to get you started.

One decision that can be an important (and fun) part of writing developer-focused documentation is deciding if a code sample would help illustrate your point more effectively. If the answer is yes, then what type of sample should you develop? Of course, that depends on the subject. Your article may be about a tool or utility that you've developed, in which case, the decision is already made for you. Or you may be writing about a new feature in an application or about a technique or process. Again the choice is yours but as I said earlier, how-to articles and walkthrough are usually much more effective that long descriptions. When deciding on a sample, it is best to keep it as simple and focused on the subject as possible. It's easy to get carried away and add all kinds of bells and whistles that will usually tend to muddle the message you are trying to get across. So focus should be your watchword.

There is debate as to how important it is to include certain standard code-writing practices in your samples. Some, such as comments, are no-brainers as the whole point of including the samples is to teach. However, whether to include other items such as including error handling is a much more nebulous. Again, it comes back to focus. Adding simple error handling, such as the following shouldn't be an issue:

Try
   ...
Catch excpt As System.Exception
   MessageBox.Show(excpt.Message)
End Try

Anything more elaborate should be carefully weighed against creating a distraction from the message. One compromise is to add a note at the beginning of the article that says the sample is used to illustrate a point and doesn't necessarily reflect good coding style. You may then want to provide a link or reference to another article on good coding practices.

You will usually want to add a paragraph or two that describes the more tricky parts of the sample or the parts that you want to emphasize. You can reduce the need for this extra text by including clear, concise comments to those areas in the code that may not be obvious. You should avoid commenting every little section or construct as this also takes away from the point of the sample and may alienate the reader by pointing out the obvious.

Another important aspect to consider is whether to present your sample as a code snippet or as a sample that the user can drop into an application "as-is." This depends on the circumstances and writer preferences. However, where practical, complete samples are much more effective than snippets as long as they aren't too long. Code samples that go on page after page can be irritating and counter-productive. For those types of procedures it is better to include them in a package that can be downloaded by the reader. Remember, put yourself in the reader's place and think which option would be more convenient for you.

I will end part 1 of the blog here. Sorry that this blog is so long but this subject is one that I'm passionate about and know that it would be great if I could get other developers interested in sharing their knowledge and experiences. I will post Part 2 shortly.

Comments