On Writing And Formats Of Written Communications

And when to employ them.

Every word you write / speak, imagine you are buying at 100 Rupees.

Pick right/all formats + content based on audience.

Ideal audiance: an intelligent person, who doesn’t (yet) know what you are talking about, and aim that they do (know what you talking about) afterwards.

Entropy: measure of information content. Maximise the rate of change of entropy.

Be grammatically accurate. Capitalize. Exactly one space after punctuation. None before. Don’t is not the same as dont.

Maximally unambiguous: if it possibly to twist your words to mean anything other than what you meant, assume that-meaning is the only meaning that is being communicated. Exercise: why was dash needed between that and meaning above?

Avoid pronouns as much as you can, if sentence can be re-written by removing pronouns(/them), do consider.

Rewrite. Many many times.

Choice of words must always be intentional. Not the first word that came in your mind, but the most appropriate that is available to comprehensively deliver the message you are trying to communicate.

Think a lot before and when writing. And keep thinking when you are done writing. And then re-write some more, and then think some more. And more.


140 chars. 280 if you are not very smart or are lazy.

When to: everytime anything of importance happens.

When/why to tweet: We are busy people. We NEED to know, ANYTHING worth knowing. You are judged for what you consider is (worth knowing).

You will never fail by telling too much. You will always by using too many words/minutes to do so.

Pick (broadest possible) channel.

When in doubt: over tweet.

Assumption: the person being tweeted is generally in the know (of what is happening), and is only waiting for updates on when they happen. Repeat: they already know what you were trying to achieve or why you are doing something, they only need to know when you have done.

Format: When - What. eg published a blog post. Restarted the service. Bad tweets have to specify when as tweets must be timely. When = now. Or when = “I just realized” (eg I am/going to be late).


Someone is going to do something and they lack some information, past context, important considerations, brief’s role is to help them take actions.

One way to think about brief is in military context. You are going to storm into a hostile situation, you need to be briefed about thing so you do not get killed, and successfully carry out the mission you are putting your life in danger for.

Before I send you for mission, I brief you. You remember the brief precisley, everything picked in brief is important for life and death on the spot decision making. There is constant gunshots in background, so you do not have forever to brief, therefore the word.

De-brief: You were briefed, you went for mission, you came back, you debfrief me, you know I already know the brief, you went in the terrorist hideout, you saw something, you did something, you de-brief, as a guide to me who is going to go in next.

Brief will tell you precisely what is to be done so you can carry it out successfully, in case its related to task, or for going into investor meeting etc. Brief will also tell you importance of factors so you can take informed decisions about how much sacrifice is acceptable to achieve the goal.

De-brief is your report of the mission after the mission. Did investor show doubt. Did the thing go live. Did we achieve the reduction in bouce-rate we were expecting.

Brief. Bang. Bang. Bang. De-brief.

Tasks. Projects. Meetings.


Briefs are factual, to the point, minumum words possible, everything related together, to be interpreted by a person who need be repeated to.

Blog is for civilians. Or for situations that are not hostile. Everything is hostile, but sometimes we pretend they are not, to keep blood pressure in control.

Among communication tools, blog is an educational one.

The purpose is to give context, but also to give more details. More conversational. Kind of things you talk about in parties or with friends, assuming you spend time with and have intelligent friends.

It is not rambling. Going from one direction to another. It has a topic.

Blog is newsy. Something has happened, or some new realization has been arrived at. And that is being communicated. Or we are looking at past, reviewing past decision or event, reflecting.

Some tweets and briefs deserve a blog post. Most papers, tutorials and books deserve a blog post.

A little bit of why. Teaser may be.


A lot of blog posts should be papers. If its not a casual topic, say site was down yesterday.

Papers have structure.

They are dense, precise, technical, with details, boring.

Papers are written to communicate decisions. Findings.

They are meant to be taken seriously. Then need to be reviewed. Any mistake in paper can mean the business is going to not achieve its true potential.


Some blog posts should be tutorials.

Tutorials are for beginners. They omit details, simplify things at beginning for beginners.

They are step by step, giving answers to common questions, they are hopefully not boring, should be small, so can be finished in relatively short duration.

They should be referred to when someone starts on something for first few times.

They are structured for flow. They are written based on epistemological analysis, based on what someone knows so far, starting with a regular intelligent person with no specific domain knowledge, but interest in learning.

Start with gobal common, a base of assumed knowledge that you believe everyone in the world has.

Then start introducing topics one after another. At any time only one new idea must be introduced. Only once the first idea has been given due justice next idea must be touched upon.

Tutorials must avoid jargon, or explain them profusely before assuming the person who hears it for first time understands it as well as someone who has been slowly trained about the jargo over last few months or years.

Goes without saying: tutorials are not documentation, nor blog post, nor papers, nor SOPs, nor books. Tutorials can be brief or tweety, short or very short in length, skeletal if time is of essence, but skeletal is better than none.


Documents are authoritative. They have details, every last one of them. They are the single source of truth.

If any information/decision changes, ideally every bit of content in format should be updated to reflect the new reality, but in documentation is critical, changing decision without updating documentation is cardinal sin.

As soon as anyone has any doubt, in tutorial, book, paper, they will refer to the documentation (as other formats can go stale over a period of time), so they must always be accurate.

Examples of documentations:


Standard Operating Procedures, SOPs, are very specific kind of documentation.

Whenever an action has to be performed more than once, that action needs a standardised procedure.

Everyone, no matter who, no matter how dire the emergency, fire, people are dying on the floor, literally, MUST perform the action in exactly the way they are written in SOP.

Any deviation from SOP is treated viscerally as sin, of kind that invokes the emotions of vengence and wrath.

Scratch Pads

These are temporary documents. Writing is a tool for thinking, for visualization. They can be google docs or sheets.

Scratch pads are time based (note to self: improve vocabulary), eg project tracker. PR-FAQ while comments are being sought. Working documents where excessive collaboration is required etc.

Every kind of document can start as scratch pad. Most other documents, that don’t really matter for the org in log run, people who are joining new need not worry about it, etc, temporary, throw away stuff.


What you are reading is a (mini) book.

Books are for everyone in the organization or relevant function to read, ideas and philosophies/thought process, and assumtions and dreams, that needs to permeate to everyone, every thought, every action.

Some books may accompany some papers.

Books answer existential questions, and are written with goal of communicating the answers to everyone who joins the organization.

The books are organization’s religion.

Other Tips

Table Of Content

Immobile v2


Rust: Or Type

Link Log

August 2020

July 2020

June 2020

May 2020

April 2020

March 2020

February 2020

January 2020


Books Have Read / Recommend

Product Management Books

Badass: Making Users Awesome


Five Cs of An Organisation

Success and failure of encryption

Open Source

Observer: Observability for Rust

Realm: Web Development Framework Using Rust and Elm

MartD: Server To Browser Messages

On Writing And Formats Of Written Communications

Rust Stuff

Rust feature flags

Why is diesel not compatible with async?

Making Postgres Only Diesel Code To Also Support Sqlite

Rust Git2’s Concepts

Git Hash And Build Date In Rust Build

Systray Only Native App In Rust

Software and Tools I Use Often


DNS Over HTTPS Controversy

The Patel Motel Cartel

Standalone Complex


January 2020

Word Of The Day





Nix On OSX Catalina

Postgres: WAL / Logical Decoding

Postgres: Listen-Notify



Go All The Way

SSH Commands



Nu Shell

SHA256 vs SHA224

Pronouns Bad


Web Components

Early Return