Write because you have knowledge that you want to share with others, and by doing so, you may benefit from getting recognized for your talents through a higher profile within your company, or a promotion. If you’ve spent your education and career focused on developing strong and deep technical skills, learning how to write well can make you stand above your peers.
If you think about all the famous scientists throughout time, they all published. I’m currently listening to “The Origin of Species” by Charles Darwin and find it enjoyable and very easy to follow even though this is not my area of expertise. To me that is the sign of a great writer: to write so that people outside of the field can understand the topic. I found this website, 25 Great Books By Legendary Scientists, that lists a few more books in the same genre that may lead to the conclusion that these scientists became famous as a result of their writing! If they had never written, would we have heard of them?
OK, you may not become famous (or rich) as a result of writing an article or book about your field, but it might bring you some satisfaction and others a deeper level of understanding in your area of expertise.
Two prolific authors in the IM – DB2 area who I think have raised their profiles via writing are Roger Sanders and Paul Zikopoulos. Both are very talented, but with their writing, they are seen as being leaders in their fields.
In my current assignment for developerWorks I’m working as the acquisitions editor for IM content. I’m receiving many proposals for articles. Believe me, there are many people who want to write about DB2 and other IM products, and for that I am very happy. I do, however, see varying levels of quality. My attempt with this post is to give some guidance to anyone who is interested as to how to improve their skill as a writer. It is a skill that can be learned, so don’t fool yourself into thinking that if you don’t have an English degree that you are incapable of improving this skill. And also, don’t let the fact that English is your second language stop you from trying to improve your skills. I work with many authors who are not native to English and would like to single out Martin Oberhofer and Matthias Nicola as two such people who are excellent writers despite being native German speakers. How did they do it? I bet they’d both say that it was hard work!
So, here’s what I think you should consider as you plan, write, and edit:
1. Schedule time to write. If you wait until you’re “in the mood to write”, you’ll never get anything done! Set goals for how much you want to accomplish and move to another section if one is causing you grief. Reward yourself as targets are reached.
2. Have a strong outline before you start to write. I know it sounds cliché, but the more up front planning you do, the easier the writing will be. Even for technical documents, you should “tell a story”. Have a beginning, say a problem that needs to be solved; a middle, the search for a solution; and an end, a strong conclusion. Choose an interesting topic that is not routine, found in the manuals, or elsewhere in developerWorks.
3. Let some personality show through in the writing. There are some cases where dry, factual writing is required, but where it’s not, let the writing be conversational or slightly casual to be of interest to the reader. Always think of your reader. Even if the writing is just for a school paper, the last thing you want to do is to bore the reader so that the ending is never reached.
4. Diagrams and tables are useful, but ONLY if they are tied tightly with the text. Don’t put them there just for filler because they’ll never be looked at. The best idea is to add reference numbers to the diagrams and have text to lead the reader from one point to the next. If that sounds like too much work, maybe the diagram isn’t really needed.
5. No one’s writing is perfect… every author needs to review and revise their work many times. Most authors get quite tired of reading what they’ve written by the time it is “finished”.
To make revision as easy as possible, I suggest that each time you go through your draft, look for one specific thing at a time. For instance, the first time through, check that you are using the active voice instead of passive. Next, go through and look to make sure headings and lists use parallel wording. Next, look for words that are commonly spelled incorrectly that will not be caught by a spell checker. And so on.
6. For everyone, but especially if you are English-second language, consider reading the text out loud or have the computer read it to you. You may be able to hear problems in the wording easier than you can read them. Also, look at past comments you’ve received on writing assignments. Likely you often make the same errors every time you write, so pay close attention to how your previous errors were corrected, and go through your document to specifically focus on improving these problem areas. Learn from your mistakes!
7. There are a lot more details that will help you, so I encourage you to get a copy of Roger Sanders' book, From Idea to Print: How to Write a Technical Book or Article and Get It Published.
8. If you’re writing a technical document, your goal is not to make it “beautiful”… your goal is clarity. You want to ensure that anyone who reads what you’ve written understands your technical messages.
9. Get others to review your draft, but don’t take feedback about your writing as an insult about you personally. If you do, you’ll never be able to write. Not many people can write a first draft that is perfect… but with many revisions and attention to feedback you can get as close to perfection as possible.
10. Size matters. There are different ways to present your content. Is it an article (average 10 pages or fewer when printed), a tutorial (average 20 to 30 pages when printed), a white paper, a series of articles with a constant theme, or a book? For developerWork’s definitions of articles, tutorials and knowledge paths see: A step-by-step guide for authors to create articles, tutorials, and knowledge paths for publication on developerWorks. White papers are typically for research purposes and books are typically 250 pages.
Many of my tips were adapted from tips found in Roger Sanders’ book “From Idea to Print: How to Write a Technical Book or Article and Get It Published”. This book covers everything that you need to know & do in order to get an article or book published. Becoming a writer isn’t nearly as difficult as you think, but it does take work.
Other resources to consider:
- Writing for IBM developerWorks
- How To Edit Your Own Writing (Self-Editing)
- Authoring with the developerWorks XML templates: A step-by-step guide for authors to create articles, tutorials, and knowledge paths for publication on developerWorks
- “About.com Today” Newsletter about writing. Much of this article is about grammar and punctuation. A very good read if you are new to writing.
- About.com article: “The Best Advice on Writing - Ten Writers Recall the Best Advice They Ever Received”. This is a really good article that will give you tips from established authors.
- If you want to get ahead and achieve the most from your technical talents,
learn from Sam Lightstone’s book “Making it Big in Software”, that one of the best ways to get a
promotion is to do something that makes you stand out from your peers. Publish,
file patents, join groups, present about your topics, etc. Do what you like to
do and what makes you feel appreciated. Writing and presenting will make you an
instant expert in a topic and will make you stand out.
There was lots of advice in Sam’s book about getting a promotion and rising in your field, but the one thing that stood out for me is that you should become the expert in YOUR DOMAIN. Whatever that domain is... become an expert. It doesn't take long, but unfortunately it is rarely done. So, it would be fairly easy to stand above your peers if you just invested a bit of time each month to learn something new about your domain.
- Developing Quality Technical Information: A Handbook for Writers and Editors, 2nd Edition
- By Gretchen Hargis, Michelle Carey, Ann Kilty Hernandez, Polly Hughes, Deirdre Longo, Shannon Rouiller, Elizabeth Wilde
- Direct from IBM's own documentation experts, this is the definitive guide to developing outstanding technical documentation--for the Web and for print. Using extensive before-and-after examples, illustrations, and checklists, the authors show exactly how to create documentation that's easy to find, understand, and use. This edition includes extensive new coverage of topic-based information, simplifying search and retrievability, internationalization, visual effectiveness, and much more.
- DITA Best Practices, Video Enhanced Edition: A Roadmap for Writing, Editing, and Architecting in DITA
- By Laura Bellamy, Michelle Carey, Jenifer Schlotfeldt
- This is the video enhanced eBook version of the print title. Watch video demonstrations to see how to implement some of the advanced features of DITA discussed in this book. With these videos you’ll learn to code short descriptions, links, conditional processing, and content references. In addition, you will find instructions in the last few pages of your eBook that direct you to the download site for the set of DITA sample files used in examples throughout the book.
- IBM Style Guide, The: Conventions for Writers and Editors
- By Francis DeRespinis, Peter Hayward, Jana Jenkins, Amy Laird, Leslie McDonald, Eric Radzinski
- The IBM Style Guide distills IBM wisdom for developing superior content: information that is consistent, clear, concise, and easy to translate. The IBM Style Guide can help any organization improve and standardize content across authors, delivery mechanisms, and geographic locations. This expert guide contains practical guidance on topic-based writing, writing content for different media types, and writing for global audiences.
If you have a subscription to Books 24x7 or Safari Books Online, you should be able to access all four of these books in electronic format. If you choose to purchase a copy, purchase the IBM Press books directly from the publisher and get 35% off by using this code at the FINAL CHECKOUT: IBMEXPERIENCE. There is also an ebundle and video enhanced to get all three books at a special price.
Keep your technical skills up to par, but go the extra step and learn how to wow the world with your knowledge through writing!