How to write an engineering blog?

Writing is an unnatural act. According to Charles Darwin, “Man has an instinctive tendency to speak, as we see them in the babble of our young children, whereas no child has an instinctive tendency to write”.

It’s natural for engineers to convey their thoughts verbally. But when it comes to writing, it’s a laborious task.

Speaking and writing involve two different personalities. For engineers, the spoken conversation is instinctive. But for writers, it’s the writing part that is instinctive.

That’s why it’s important that writers and engineers collaborate when it comes to blogging.

If you’re in the field of engineering, then you’re probably looking for ways to engage with your audience. Blogging is an effective way to build relationships with your customers and prospects, it also helps you stay up-to-date on industry trends. 

Engineers should look at blog posts as a way of crystallising ideas like the code.

The major challenge is to identify what to blog.

Being an engineer, you have insights into technology that may not have been elucidated. You need to ask what others do not understand, and how can I explain it clearly.

You can also highlight the specific problems that you encountered, methods that proved to be a workable solution, and some advantages/disadvantages of alternative solutions.  

As a writer, your role is to sieve the content from the fat and give life to the technical jargon like characters in a novel.

The six principles for good storytelling are 1. Absence of lengthy verbiage; 2. total objectivity; 3. truthful descriptions; 4. extreme brevity; 5. audacity and originality…and; 6. show and not tell. Check this link for the art of storytelling: https://www.linkedin.com/pulse/skill-every-leader-needs-storytelling-katya-andresen/

Before you start, draft a template – write the main headings first. Then focus on sub-headings. Under the sub-headings, write whatever comes to your mind. Don’t focus on grammar. Whatever knowledge you have, put it in writing. You can revisit and edit. Make sure all the knowledge is captured in the blog post. Put images where possible. Get feedback from your peers.

The next step will be editing. Editing is where you fix up the grammar, spelling, and punctuation. Make your sentences short and easy to read. Write in the active voice. Trim wordings if the sentence can convey the meaning correctly. The presentation and grammar are equally important. They help express the meaning.

Check out this link for writing best practices: http://www.covingtoninnovations.com/mc/WriteThinkLearn.pdf

If you need help in writing an engineering blog or editing, email me at abeeshthomas@yahoo.com or call +65 82086393

9 steps to create Technical Documentation

1. Read the Marketing Requirements Document (MRD) and functional specification. The MRD should list out clearly the documentation requirements.
2. On the basis of MRD and functional specs, create a documentation plan that includes
•  Product name, scope, and purpose
• Milestone dates 
• List of documents that will be created and/or updated. If the project is about updating an existing product, list the features to be documented. If the project is about releasing a new product, additional planning is required. There are multiple customer documentation deliverable types a project could require, ranging from a single-paged addendum to a context-sensitive online help system.  
• Features that will be documented
• Work estimate and committed schedule for documenting each feature or completing each document 
• Committed documentation milestones
• Documentation Reviewers including review schedule. There are 2 ways to conduct a review, collect edits individually from each reviewer or hold a review meeting to review everyone's comments. Multiple reviews may be required. You can also use Adobe's Shared review process to collect feedbacks from multiple reviewers.
• Depending on the program, include any training material needed for the Launch.
• Risks, assumptions, and dependencies. Include the following: Main risks of the documentation project (e.g. last minute feature additions), probability of each risk, Impact of each risk, Risk mitigation plan, Owner of the mitigation plan)
• Affected BOMs and/or document numbers
•  Doc approval process and approvers (outside the tech pubs team)
• Documentation delivery and distribution plan.
Distribute the plan to the core team members: PLM (Marketing), R&D lead (Engineering),  and PM (Program Manager) who will review and approve the plan.
After the approval, create the draft document by attending the core team meetings, interacting with the application, studying design documents, asking questions to the testers/developers.
Send the draft to the reviewers identified in the documentation plan.
Update the documents as per the review comments, address all the major and critical documentation CRs and defects identified during the documentation validation.
Obtain the documentation approval from the designated reviewers/approvers.
Generate the final version.
Check in the final document into the build branch.

Steps to create a brochure

 

10 Rules for Writing First Drafts

Some good readings:

https://medium.com/better-marketing/10-must-read-lessons-on-writing-from-literary-critic-william-zinsser-35f7a281250c

Technical Writing in an Agile Environment

While working at Savi Technologies, Singapore, the company strictly followed the Agile Scrum methodology. I was with the Typhoon team. Daily the team gathered in one of the cubicles to discuss what we did the previous day, plans for the day, and any blocking issues. During the initial days, I came across the below slangs that were foreign to me. 

• Scrum Team: A scrum team typically consists of five to nine people that include a Scrum Master, s/w engineers, testing engineers, and a technical writer.
• Stories: I used to wonder why they call the feature request as stories. Is it some new adventure stories of Hardy boys or Enid Blyton’s? But I liked the term ‘stories’, It describes why you want that feature to be included in the application.
• Product Backlog: The “product backlog” is the list of stories in order of priority. The stories at the bottom of the backlog tend to be just ideas and perhaps still rather big chunks. They must be broken down into smaller stories as they approach the top of the list. Some people use the concept of an “epic” to group related stories and keep them together as they approach the top of the list. The requirements are collected in a prioritized product backlog by a product owner.
• Sprint Backlog: The “sprint backlog” is the list of stories to be tackled in a particular sprint. During the sprint planning meeting, the project team determines which backlog items go into the sprint. No one is allowed to change the sprint backlog, which means that the requirements are frozen for that sprint. The sprint must end on time. If requirements are not completed for any reason, they are left out of the release and returned to the product backlog.
• Sprint: The iterations and incremental cycles in Agile are called sprints. This is an analogy to what happens in a race. We essentially "sprint" towards a race for completion of the development of software, testing, and documentation. The “sprint” is a period often three weeks during which the development happens. During the sprint, the Scrum team works in close cooperation and meets every day to discuss and resolve any problem.
• Sprint Planning Meeting: There’s a planning meeting at the beginning of the sprint and a retrospective meeting towards the end. The idea is that each sprint delivers a potentially shippable product. In the retrospective meeting, each members' performance is evaluated. Members are free to criticize one another. During my tenure, the ID team received both appreciation and criticisms. But at all times, we took the criticisms in a positive manner and ensured that mistakes were not repeated.
• Scrum defines 3 roles: The product owner creates and prioritizes the backlog, defines the stories, and decides what goes into the next sprint. The scrum master works with the team, fixing anything that’s stopping the team from working. The team does the development.
• Story Points: When estimating the stories, they use “story points” depending on the number of man-hours and resources to finish the task. The story points are expressed as a number, based on the relative complexity of the work required. All the members are given a points card and each member decides on points that need to be allocated for completing a task. And based on the majority of votes, the points are allocated. And they need to justify, why they think, the user story deserves that many points.
• Burndown Chart: This is a graph that lets the team know how much work is left and completed in the sprint. We used Rally to generate the chart. Using this tool, any member of the team or a person outside the team can see at a glance whether the team will complete the work for the sprint.

The good part about Agile development is that writers are involved in product planning, and the documentation development timeline is factored into the product release. Being part of an Agile team has the advantage of making you and your work far more visible. We all met in a meeting room for the sprint planning to commit to the deliverables. We used a tool by the name Rally to define our goals, achievements, pending tasks, etc.

In an Agile environment, developers, QAs, and writers work together to meet deadlines. In addition to the documentation, I also tested features and logged defects. This helped me in gaining good product knowledge. 

Two key points in ensuring a successful scrum are 

• having a set of agreed deliverables and 
• breaking the assignments into small tasks that can be estimated and tracked 

In Agile, any problem that members face is the team’s problem. The role of the Scrum Master is to get rid of any impediments interfering with your work. For example, if you cannot start your documentation because developers haven’t finished coding, then that becomes an obstacle. You can request them for a sample prototype. You do not have to wait until the completion of the coding to start the documentation since that can cause your work to spill over to the next sprint. 

I believe that every company that hires a technical writer should have a well-defined process. It's paramount for documentation development to be integrated with software development.

If you have any questions, email me at abeeshthomas@yahoo.com

7 Deadly Sins of Technical Writing

In my experience as a writer, I've produced documentation that I'm proud of, but I've also written some that didn't meet my own standards. 

 Here are seven problems to look out for to avoid these pitfalls: 

1. Poor Organization: Make sure that your users can easily find the information. It is tempting to organize the content as per what you see in the software application. But ideally, you must ask what the user wants and based on that you must organize your content. 
2. Inaccurate information: Sometimes you may receive wrong information from Engineers and document this piece of information. To fix this issue, you must get your content reviewed by key stakeholders like product owners, scrum masters, engineers, and QA guys to check the veracity of the content. 
3. Outdated information: This occurs when the product undergoes enhancement but the changes are not communicated to the writers by the development team.
4. Incomplete information: Users often need more information than you give them. You must not only document how to perform any task, but also provide conceptual information answering what, when, and why. Your goal should be to tell the users everything they need to know without overwhelming them.
5. Bad sentence structure: The general rule of thumb for technical documents is to keep your sentences short. Whenever possible, use tables, bullet points and numbered lists to organize information.
6. Poor word choices: There are many words that mean approximately the same thing. Depending on the situation, you must make the judgment. When choosing between one or more words ask the following questions:
   
   Which word is the most clear?
   Which word is the most unambiguous?
   Which word is the most accurate?
   
   Once you have made a choice, the next step is to be consistent. Use the same word every time the situation and instructions are the same. For example, if you wrote, Click the OK button or Click OK, the first time, use the same statement every time you expect the same action. 
7. Incomplete Review: Never take your writing for granted if your document has not undergone peer and technical review. You will be surprised to come across errors after review. So it’s worth the effort to get your documents first reviewed by a fellow technical writer and then by Engineers/QA/PLMs. During peer review, you can catch some good errors like missing links or broken cross-references which are normally missed out in the technical review.

Ramblings on Technical Writing

The secret of good writing is to strip every sentence to its cleanest components. Every word that serves no functions, every long word that could be a short word, every adverb that carries the same meaning that's already in the verb, every passive construction that leaves the reader unsure of who is doing what - these are the thousand and one adulterants that weaken the strength of a sentence.

Clear thinking becomes clear writing; one can't exist without the other. It's impossible for a muddy thinker to write good English.

Thinking clearly is a conscious act that writers must force on themselves.

Writing is a hard work. A clear sentence is no accident. Very few sentences come out right the first time, or even the third time.
Tell me, and I will forget. Show me, and you will involve me. Involvement is the first step toward understanding. If you're concerned about whether in any passage or chapter you are telling rather than showing, there are some questions you can ask yourself:

Are you allowing the reader to see what's going on? Showing means having actors do things that excite our interest, making those pages visual, letting us see what happens firsthand.

How to show? Sight is our primary sense. We prefer to witness an event. Which is why, we must show a story instead of tell a story. Show, don't tell.

Verbs are the most important of all your tools. They push the sentence forward and give it momentum. Active verbs enable us to visualize an activity because they require a pronoun or a noun or a person to put them in motion.

Make active verbs activate your sentences, and avoid the kind that need an appended preposition to complete their work. Use precise verbs.

Most adverbs are unnecessary. You will clutter your sentence and annoy the reader if you choose a verb that has a specific meaning and then add adverb that carries the same meaning.

https://www.quora.com/Why-are-adverbs-considered-to-be-evil

Mark Twain - If you catch an adjective, kill it !. Most writers erect a Great Wall against the process of eliminating all but a minimal number of adjectives and adverbs.

Most adjectives and adverbs are dispensable. The easiest ones to dispense with are "very" and "quite".

Adjective surgery can be painful until you practice it rigorously and examine the results.

There are several rules for determining which adjectives to keep:
An adjective that is a necessity
An adjective that stimulates the reader's curiosity and thereby helps move a strong along. Example: He has a pursued look, wouldn't work without the adjective. Moreover, the adjective raises curiosity about why he had the pursued look..

An adjective that helps the reader visualize the precise image you want to project.

An adjective of course modifies a noun. An adverb modifies a verb,. Most adverbs require the same tough surgery as adjectives.

Leah wished he would call soon. The meaning of soon is implied. The adverb is unnecessary. The sentence is stronger without it.

A frequent error is the use of two adverbs. She really, truly cared for him. Would you eliminate "really" or "truly"? You could take out either.

Before you begin eliminating all adverbs by rote, keep in mind that sometimes adverbs can be helpful. There are 2 adverbs in the following short sentence. Each conveys something different.

He ate heartily, happily.

Heartily connotes eating a lot, "happily" connotes taking pleasure. If it's the author's intention to convey both meanings, the adversb should be retained. He ate without either adverb tells us little.

The verb should agree in number with its subject. So a plural subject requires a plural verb, and a singular subject rquires a singular verb.
A test was completed last week. (singular)
Several tests were completed last week (plural).

Ensure that your verbs agrees with your subjects.
She works every day. (singular)
They work every day. (plural)

He has the answer. (singular)
They have the answer (plural).

Strong verbs shorten sentences and convey direct memorable messages.

Subjects connected by and require a plural verb.
The ceiling panels and fasteners have been fabricated.

The software designer and the graphic artist agree that we should market the new instructional manual immediately.

A personal computer and a photo copier are essential business tools today.

Note: Sometimes words connected by and become so closely linked that they become singular in meaning, thus requiring a singular verb:

Bacon and eggs is my favorite breakfast. My name and address on the inside cover. Simon & Schuster is an excellent publishing firm.

Singular subjects connected by either...or, neither...nor, and...not oly...but also require a singular verb.

Either the post-operative therapy or the inflammation is causing the acute pain.

Neither the district engineer nor the superintendent has approved the plans.

Not only the cost but also the design is a problem.

Place the adverbs only, almost, nearly, merely, and also as close as possible to the word they modify.

The engineer had almost finished the specifications.

Choose adverbs, not adjectives, to modify main verbs:

Our accounts predicted accurately that cash flow would be a problem.
The manager asked quickly for the up-to-date estimates.
The test engineers calculated roughly the expected power.

Prefer active sentences. Use a passive sentence when you don't know or don't want to mention the actor. A style that consists of passive constructions will sap the reader's energy.

Use a passive sentence when the receiver is more important than the actor.

Avoid wordiness:

Use concise, direct sentences. The principles of writing direct, concise sentences

The verbs should agree in number with its subject...So a plural subject requires a plural verb, and a singular subject requires a singular verb.

The geologist has completed the tests. (singular). The geologists have completed the tests. (plurarl).

A test was completed last week. (singular)

Several tests were completed last week. (plural)

Ensure that your verbs agree with your subjects.

She works every day. (singular)
They work every day. (plural)

She is the candidate. (singular).
They are the candidates. (plural)

Avoid vague use of demonstrative pronouns.
This is something to consider (better: This shortfall in payments is something to consider.)
These are difficult (better: These exercises are difficult.).

Indefinite pronouns used as subjects should agree in number with their verbs:

Anyone likes to receive a positive performance review. (Anyone = singular; likes = singular)

Several were contacted before we chose a final canddidate (Serveral = plural, were = plural).

All of the sugar was tainted. (All of the sugar = singular, was = singular).

All of the employees were notified of the new vacation policy. (All of the employees = plural, were = plural)

In case of REST API documentation, should we keep it concise with just a one-liner description? Here’s my take: While minimalism has its merits, applying it here results in poor UX. For REST APIs, the documentation is the interface—the only interface. Developers don’t have a visual UI to explore or experiment with, so the documentation must provide all the information they need to understand and use the API effectively. Why is comprehensive documentation essential for REST APIs? REST APIs lack a visual interface. Developers depend entirely on the documentation to grasp how the API works. Any missing detail forces them to guess or waste time deciphering functionality. Good documentation isn’t just about presenting data; it’s about removing friction for developers and helping them succeed.