Sell yourself, sell your work

My writing rules are:

* Explain, don’t “sell”. If something is significant and you explain it well, the significance will be obvious without artificial emphasis.

* Explain, don’t “persuade”. Don’t assume agreement before or after. Make your reasoning clear. Don’t assert credibility or pressure for acceptance.

* Clarity and brevity compound each other. If you are clear, you don’t have to spell out every detail, or review important points.

If you find yourself trying to explain what you have explained, you have not been clear or concise and are now spiraling. Rethink. Rewrite.

* Finally, state your main point/purpose up front. For everything, every section, every paragraph. Gets attention. Filters readers by relevance. Assists clarity & brevity.

——

Avoid mixing multiple or deeper points, that are better communicated separately.

Find an unmissable visual way to indicate where the first point/purpose was accomplished, and additional material has a related but new purpose.

> Explain, don’t “sell”

> Explain, don’t “persuade”

Know your audience. A library on github targeted towards developers does both selling and persuading via a good explanataion.

Thank you. Theso are excellent. I'll be coming back to this comment often until I internalise it all. And I don't even write in public, but I want to improve, for work, and for myself.

Ps: the irony on the second paragraph of the third point wasn't lost ;)

> Finally, state your main point/purpose up front. For everything, every section, every paragraph. Gets attention. Filters readers by relevance. Assists clarity & brevity.

My grad school advisor said to me that "the first N sentences should be the most import N sentences" when writing papers

> via a good explanataion.

That is the point I was making.

Note the quotes on “sell” and “persuade”. That’s a hint. Meaning a lot of words meant to sell or persuade are actually harming those purposes.

Three word highly opinionated statements, like my paragraphs began with, are best viewed as strong (re-)prioritization. Not a prohibition on nuance once the point is understood.

So, I appreciate and agree with your nuances.