How to create a documentation plan

A documentation plan lays down a blueprint for the whole writing project. As a writer, before you embark on your documentation project, create a proper documentation plan and get it approved by key stakeholders. This will establish your credibility in the event of any crisis. It is important to study the marketing/customer requirements document. Ideally, the requirements document should state clearly the features to be documented, the depth of information to be included in the documentation, and the format (HTML, PDF, Word, etc). The next step should be to study the functional specification.

On the basis of MRD and the functional specs, the documentation plan should include the following details:

• The 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 can be multiple deliverable types needed, ranging from a single-paged addendum to a context-sensitive online help system.

• Version control tool for managing the source files, for example, Snapshot CM, Rational ClearCase, git.

• 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 feedback 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, and Owner of the mitigation plan)

• Doc approval process and approvers

• Documentation delivery and distribution plan.

Main components 

• COVER PAGE summarizing the name of the project; organization, and copyright or confidentiality statements.

• Table of Contents – Proposed chapters and their tentative content.

• An introduction that covers the purpose and scope of the plan.

• HISTORY (or REVISION LOG) showing the revisions the plan went through, with dates, the names, and titles of the persons who wrote different versions.

• RISK FACTORS – What are the dependencies to complete the documentation? Which critical factors may bring this project to a halt? What are the impact (H/M/L) and the probability (H/M/L)? What measures should be taken for such an eventuality and who are the mitigation owners.

• Reviewers and Review Process displays the names, titles, and contact information of the writer and all stakeholders involved with the documentation project.

• Product features – what are the features that will be documented.

• Document specs – Is this going to be an online document, a printed document, or both? Will it be single-sourced? Will the project be using a client template? Which version control tool will be used for managing the documentation source files.

• Schedule – What are the milestones in the development of the document? What is the effort required? When should the review cycle(s) be finished? How many rounds of reviews should be allowed? What is the start/end date for the whole project?

Kickstart every technical writing project with a well-crafted and approved plan. 

Technical Writing Interview Questions

 1. Analyse the code

public final class Solid

{

  public static int atomic(int n)

  {

    if (n < 0) {

      n = -n;

    }

    int d = 1;

    while (n > 9) {

      ++d;

      n /= 10;

    }

    return d;

  }

  public static void main(String[] args)

  {

    System.out.println(atomic(103));

  }

}

2. What's the difference between API and SDK?

3. What's the difference between Class and Object?

4. How do you create code samples, what are the important things to note when creating?

5. What's the purpose of Version Control Tools?

6. Tell me about a time you failed or made a mistake.

7.  Tell me about a time you had to manage conflicting priorities.

8. Tell me about a time you disagreed with someone.

9. Tell me about yourself.

How I write a White Paper

An Overview of White Paper

White papers are a favorite marketing tool for companies. Companies aim to sell products as solutions to their customers through the white paper. The white papers educate readers and enable them to make decisions in choosing the solution that suits their needs. In this case, the white paper becomes an excellent marketing and SEO tool that advertises the company's products or services. Check this link about when you need to have a white paper.

However, writing a white paper is a challenging task. It involves an in-depth study of the product and its application, gathering information from the subject-matter experts, and studying the design documents. 

The objective is not only to convey information but to spark the reader's interest to engage him in reading the rest. Precision and clarity are the watchwords. Naked facts are not enough to invite a reader's invitation to the rest of the document. It's their context- the writing, the container of the information - that illuminates facts for the reader and gives them significant meaning.

The typical length of a white paper varies from 8 to 12 pages.

How I write a white paper

When embarking on the journey of crafting a white paper, my process begins with a meeting with the product owner/product manager to grasp the project's requirements. Understanding the product features and identifying the target audience is crucial. During this initial discussion, I also inquire about the expected completion date and request a product demo to gain deeper insights.

Following this preliminary conversation, I dive into comprehensive research. After gaining sufficient knowledge, I write the first draft, juxtapose words, and convey information that gives a richer experience to readers.

Occasionally, the first draft may not meet expectations. Every good writer knows that the first draft of any piece of writing rarely resembles the polished, final version. This variance can be attributed to various factors, ranging from missed details to concepts that might not have been fully explored during the initial meeting. To bridge the gap between the draft and the ideal version, I opt for a second round of discussions. During this phase, fresh insights emerge, providing a more nuanced perspective. These intricate details are meticulously woven into the fabric of my second draft. It's during this stage that the document begins to approach perfection, steadily shaping into a refined piece of work. This draft is almost a perfect piece.

Over the years, I have learned that a writer needs tough skin, for no matter how advanced one's experience and career, expert criticism cuts to the quick, and one learns to endure and to perfect. 

Writing is iterative, and a text reaches its full potential through multiple drafts, feedback, revision, and editing.

 Principal components of a white paper

• A good page layout - A good page layout ensures that language, graphics, and colors combine on a page to promote clear communication. Readers of the page will find it pleasing and easy to read even though they may not be conscious of all the page layout techniques.
• A title that arouses curiosity - A good title is a hallmark of a successful white paper. It's akin to arriving at an unfamiliar house and having the owner graciously open the door with a warm "Welcome." A good title can make a tremendous difference in the early acceptance of a white paper.
• Table of Contents - TOC helps readers in two ways: 1. they outline the structure of the document and thus provide insight into the document's organization. 2. they provide the page numbers for all sections and subsections, thus helping readers to locate parts of the document.
• Background/introduction to the document - The introduction sets the stage. It normally includes the historical background of the product and establishes the scope of the product. In essence, the introduction is a road map; it orients the reader by providing a context for the reading. In short, the introduction prepares the reader for what will follow. 
• Graphics - Graphics are essential for conveying key information in the white paper. Readers will recall one impactful graphic long after they have forgotten a thousand words of text. Create visuals first, and write text last. 
• How the product solves the problem
• System functions
• Benefits offered by the product
• Product architecture
• Evaluation criteria for choosing the product
• Conclusion

If you need help in writing a white paper, email abeeshthomas@yahoo.com. Check out my portfolio for a sample white paper.

Technical Editing and Proofreading

Faulty Parallel Construction

A failure to create grammatically parallel structures when they are appropriate is referred to as faulty parallelism.

If you want your readers to roll smoothly along from one idea of yours to the next, use parallel structure.

Both of the following sentences essentially say the same thing. Which is easier to read?

He described skiing in the Alps, swimming in the Adriatic, and the drive across the Sahara Desert. (faulty parallelism)

He described skiing in the Alps, swimming in the Adriatic, and driving across the Sahara Desert. (parallel)

Formerly, science was taught by the textbook method, while now the laboratory method is employed. (faulty parallelism)

Formerly, science was taught by the textbook method; now it is taught by the laboratory method

Nouns should be parallel with nouns, participles with participles, gerunds with gerunds, infinitives with infinitives, clauses with clauses, and so on.

Sentence Fragments

According to the grammar rule—every sentence should be complete. Meaning, it should have a subject (the main actor/actors), a verb (the main action) and, if applicable, an object (what the action happens to). Anything less is called a sentence fragment. With one caveat. Your meaning must be clear.

When a group of words is missing important information, it’s no longer expressing a complete thought. Following are some of the missing words: missing verb, missing subject, missing subject+verb, missing main clause.

Run-On Sentences

Here you will find more than one complete thought, each of which deserves its own sentence. This happens when the person gets excited about the subject matter and goes on at length without adding a period for quite a long time, and the sentence ends up sounding quite flustered and out of breath.

You must look for ways to break the run-on sentence into more than one. It’s all about keeping things clear and simple for your readers.

Dangling Modifiers

A dangling modifier has nothing to modify. It’s an error caused by failing to use the word that the modifier is meant to be describing.

INCORRECT: The experiment was a failure, not having studied the lab manual carefully.

REVISED: They failed the experiment, not having studied the lab manual carefully.

INCORRECT: Meticulous and punctual, David’s work ethic is admirable

CORRECT: Meticulous and punctual, David has an admirable work ethic.

Fixing a dangling modifier requires more than rearranging the words in the sentence. You will often need to add something new so that the modifier finally has a target word to describe.

Misplaced Modifiers

A misplaced modifier is a word, phrase, or clause that does not clearly relate to what it is intended to modify. In other words, a misplaced modifier makes the meaning of a sentence ambiguous or wrong.

INCORRECT: Andrew told us after the holiday that he intends to stop drinking.

In this example, it is not clear whether Andrew made this statement after the holiday or whether he intends to stop drinking after the holiday.

Split Infinitives

An infinitive is the form of any verb which starts with the word “to”—to go, to dance, to have written, etc.

Ideally, you are not supposed to split an infinitive by sticking extra words between the “to” and the rest of the verb. Contrary to what some grammarians say, there is no rule against using split infinitives in English. One might use them with care, but splitting an infinitive is sometimes the best way to clearly express a thought.

Infinitives should be split when the adverb either needs emphasis or wouldn’t work anywhere else in the sentence—for example:

They’re expected to gradually come down in price to about $50 to $75 each.

Placing gradually anywhere else in this sentence would create awkwardness and confusion.

In conclusion, Editing, proofreading, and formatting can make a big difference to the clarity of your work and therefore the overall grade. Contact me at abeeshthomas@yahoo.com or call +65-82086393

Tech vs. Creative Writing: A Comparison

 

Essential Tips for Writing a Technical Article

Tips for Technical Writing

• Get to the Point  - Your objective is to make the reader understand your topic quickly. The readers are not interested to spend hours reading the article.
• Avoid wordy phrases. A fundamental of good writing style is to avoid unnecessary words.  Do not say All of a sudden. Just say, suddenly. Instead of a later date, say later. The shorter, simple words or expressions make your writing more concise and, consequently, make it look and sound more professional. 
• Keep it Short and Simple - Write short sentences by eliminating punctuation without affecting the readability of the sentence. Use fewer commas, more periods, and no semicolons at all, if possible.
• Improve the Presentation - Always provide a brief description of the subject followed by steps to achieve. Provide screenshots where possible.
• Improve your Template - Use numbering if the steps are to be performed in a sequential manner otherwise use bullets. The title and headings should convey the subject matter. The headings, steps, and body text should follow a consistent format.
• Use a Style Guide - Follow your company style guide. Otherwise, use Chicago Manual of Style or Microsoft Manual of Style.

Readings

https://instrktiv.com/en/technical-writing-ux/

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.