Tag Archives: Technical Writer

Why hiring a Software Engineer as a Technical Writer is a good idea?

Before you jump the gun let me clarify, I am not talking about all Software Engineers. I am talking about those Software Engineers who have a flair for writing and who want to shift base to technical writing. I am neither in any way implying that Technical Writers from other fields are not competent enough to be recruited.

My case in point is: when a Software Engineer is rejected for a Technical Writer position for lack of experience. Now that I am done with the clarification part, let me get back to:
Why I think a Software engineer’s experience must not be discounted on grounds of it being irrelevant to Technical Writing field? And why recruiting Software Engineer as a Technical Writer is a win-win situation for both the company and the aspiring Technical Writer?
Let me answer that question by showing you a very simple analysis.

Divide the Technical Writers and Software Engineers into two groups based on the development life cycles they follow.

Note: This analysis is limited to Technical Writers in Software field because honestly I know nothing about the good Technical Writers in other fields. And yes, I know, it’s my loss.

Software Development Life Cycle (SDLC) is a structured way to develop a Software Product. Every Software Engineer takes part in the SDLC of the product he is working on. Similarly Document Development Life Cycle (DDLC) is a structured way to develop the Software Documentation and every Technical Writer typically participates in the process. Wikipedia has detailed articles on both types of methodology for the uninitiated.
I have a flowchart that depicts the different stages of both development life cycles (Stage names courtesy: Wikipedia).

Development Lifecycle

Development Lifecycle

Do you notice that some stages of the development life cycles intersect? It has to, why? Because both the parties are working on the same software product.

Typically the developers and writers will be involved in similar stages throughout the life cycle. Developers and Technical Writers need to do the Requirement analysis, they need to design their implementation/documentation, and they need to maintain the code/document that they have worked so hard to create. The other similar tasks are Testing/editing, the code needs to be tested and the documentation needs to be edited. The code has to be deployed and the documentation has to be published. The only difference lies in the implementation part where a developer works on coding the product and the writer works hard to create the document.

Do you still think that a Software Engineer doesn’t have enough relevant experience to be a Technical Writer?
I rest my case on why i think hiring a Software Engineer as a Technical Writer is a good idea by showing this Pie chart created based on statistics given by field experts.

What Technical Writers do?

What Technical Writers do?

According to field experts a Technical Writer spends almost 50% of his time gathering requirements, 10% in designing the document, 20% in actual writing and the rest of the 20% in reviewing and publishing the document.

Considering these factors:

  • Aren’t Software Engineers almost 70% job ready as Technical Writers?
  • Should their Software Engineering experience be completely discounted?
  • Shouldn’t their Requirement gathering skills, Reviewing skills be considered before rejecting them on the basis of lack of relevant experience?

What do you think? Should the skills of Software Engineers be completely discounted? Can their experience be counted as relevant experience?
Brickbats or bouquets,do send it with your feedback and opinion.


How to Edit a Document: Tips for Beginners

You have a new job and an exciting career ahead. You have dreams of being one of the most accomplished Technical Writers around.  You wait for your first task and here your manager gives you a huge word document to edit. What do you do? Edit, of course you say, but a teeny voice in you is nagging you with: “How do I begin?” “What if I miss something?” “Why am I given a document to edit when all I want to do is write?” type of questions.Do you hit the panic button or do you just jump in to do the task? My suggestion: “Have a Plan”. You can refer my earlier blog on the “The Beginners guide to Reviewing and Editing” to know more about planning your task and making a good job of it.

For now let us focus on the key points to consider when you edit. Being a good editor is like passing the litmus test to become a good writer.  You need to be a good critic to write good articles and editing teaches you to be that critic. It is less likely that you will be trained to edit, you will definitely be expected to show your ‘On the job’ competency and ‘Learning curve’.

The following general guidelines can be followed to edit any Word document:

  1. Enable ‘Track Changes’: Never forget to do that. You would not want your feedback to be misunderstood or worse ignored because it was not tracked properly. Any changes you do must be recorded and must be available as feedback for the author.
    • Ensure the Word document settings are set to reflect your name as the Reviewer. It is especially useful when you are adding comments for the author(more about adding comments in further steps). Click on File tab -> Options. Ensure your name is reflected under the ‘User Name’ Text box. Input relevant initials.
  2. Note: There are many kinds of editing; this post focuses on editing a word document containing Technical information related to the Software field. Treat it as a general thumb rule that can be modified to suit your editing needs.

  3. Add comments: in relevant places to elaborate on the mistakes you have found. Sometimes authors might find it difficult to understand their own mistakes. They might need more clarity and explanation. Adding comments is a good way to ensure that. Click on ‘New Comment’ in the Review section of Word to add comments.
  4. Review in Passes: Always do the Review in more than one pass. Do not attempt to finish your editing in a single pass. Its hardly ever efficient. The more numbers of times you read through the document the more mistakes you will find. Do a formatting check in the first pass. Technical Review in the second pass and so on.

Note: Remember to stick to your timelines , more than 5 passes is not only impractical but also unnecessary.

My Edit Sample

Checklist for Editing

Continue reading →