# Incomplete thoughts on technical writing

One of the difficult things about technical writing is that you want to be accurate, succinct, and authentic.

## Accurate

Accuracy is about the quality of the information you are sourcing from. Is the information legitimate, is it stale meaning out of date? Is the information even relevant to the processes or abstractions you want to describe?

The temptation exists to embellish a fact without context. This may be because you either do not understand the subject well enough to actually write about it or your understanding of the abstraction is context dependent eg. you know that is an essential part of the process with which you are writing about.

## Succinct

Succinct is about explaining the concept simply with the exact amount of precision required. You can say that a block chain is a state machine that is turing complete hosted on a distributed peer to peer network that is byzantine fault tolerant. Or you can say a blockchain is a decentralized p2p network which provides a virtual environment for any arbitrary application.

Succinct also exemplifies nested properties. For example you can say S{N,T}ARK which implies the acronym Succinct non-interactive / transparent, argument of knowledge. Sometimes even domain specific catch-alls like ZK can imply FHE, MPC & ZK. So the trick is to be as succinct as possible providing the key points which can be further broken down by the reader should the inference elude them.

## Authentic

Authentic is the ability to put the writing in your words. It is incredibly easy to quote, paraphrase, or copy pasta. Often it is required to do these things to properly explain the topic at hand. However, relying on them makes you lazy and disrupts your natural writing patterns.

Authentic is hard when you do not know the topic you want to write about well enough to write about it without tabs open, source materials in hand. When you can you can write without source material but then later go back and cite your sources, edit your work, add the necessary citations and credits due, then you can be authentic.

Authentic is hard when you feel injecting your own point of view into the writing will confuse the reader or distract them from the objective. The key is knowing when or if it is appropriate within the context of your writing.

Ultimately if you are providing any evaluations they should be supported by arguments that you have found to be correct. This can add value to your writing in a way that regurgitating the opinions of others cannot.

## Can you have all three though?

For the sake of learning I'll be self-critical, let's look at a recent example from a [post](https://mirror.xyz/0x8abcbb75A07d1609429aCFA9ED36c01733D9fd3E/GfVAwU9-ouCax771IPiLjhrlt8V2znF126j_9eXghDY) I wrote on distributed block building. The post clearly explains the idea with few words and a diagram. The explanation has several references where the reader not understanding a reference to EIP 1559 could dive into that topic. The writing was authentic, at the time no one else to my knowledge had written about this idea publicly.

When I received [feedback](https://twitter.com/apriori0x/status/1560229684918599680?s=20&t=EFc_KenuOF22MykEfInS1A) on the post I was reminded of network latency and sybil resistance as two hurdles to my proposal. I failed the accuracy tenant here by not including answers to fundamental questions with respect to block building.

Alternatively, the three points on the hypothetical technical writing trilemma can be satisfied *if* the writer has enough experience.

For example, in [this post](https://vitalik.ca/general/2021/01/26/snarks.html) by Vitalik he gives a simplified overview of FRI within the context of explaining ZK-SNARKs. He does it with ease. The explanation is accurate, succinct and authentic. Okay but what if you are not Vitalik or another highly skilled writer, can you average writer make it work?

Yes, but you won't defeat the trilemma anytime soon. There is a gap between average writers and great writers that will expose one of the tradeoffs in the technical writing trilemma. So, I think _nirvana_ can be achieved, it just takes alot of practice.