developer not a tech writer but have to write a lot of documentation want to learn more

spend too much time overanalyzing tech writing

want to be better

technical communication is harder

writing can help with code smells

want to communicate better

What is passive voice - "It was decided to rollback" 

who decided, why was it decided?

usually means information isnt there

"The update was made yesterday" - who made the update

often used to hide the actor

doesnt help to avoid confrontation

more examples

"the site was broken"

"an update broke the site"

A patch can be the actor (rather than a person): This patch caused 500 errors (as opposed to "Kosta broke it" or "Kosta's patch caused 500 errors")

find the bug not the blame

one concept per sentence

[ example with a lot of concepts in one long sentence]

ways to make it beter:

add links

short sentences

adding bullets

easier to read as concepts are separated out

avoid long paragraphs

paragraphs should be a logical unit

wall of texts are hard to read

avoid parenthesis


Write Read Rewrite again

IF you can edit, you an always edit to clarify

its worth it to spend to time reading and rewriting

it can be confusing what it and that is 

"I think this is a bad idea"

way to break a big wall of text into something more manageable

put important information at the beginning

ordered lists are helpful to identify specific steps eg I have a question about 3

switching a sentence with a bunch of commas can be more readable with bullet points

"The service was fixed last night and is working again. Resolving"

who fixed it? when was it fixed? whats working?

could link to the deployment log

add what was fixed

much more readable to future readers


"we decided to switch to the new API version"

could link to the new and old API versions

add the Api version numbers

explain who we is

add why the swtich happened

and when the decision is made

leave links so people can explore further


"in our meeting it was decided that Foo service is a better solution"

part of the paper trail is explaining better solution than what

you could think you have answered all the questions but may have not answered all 

helpful to explain why you didnt do something


links save time for everyone, in all contexts. It's the 2nd golden rule, along with Avoid Passive Voice. Always Include Links.

giant walls of text are hard to read

add a short summary at the top

break things into multiple lists

bold text can be helpful

Parentheses around long bug-titles e.g T12345 ("bug title is long long long")

add different code styleing to help distinguish from text `Hooks.php`

too much formatting could be distracting

always the assumption people know what it is, they dont

define the acronym when you first use it

in each space there are different ways to commuincate

slack

shorter amounts of text, doesnt need to be formal

phabricator

may want to make sure your text is readable to future readers

IRC

Gerrit

Google Docs

mailing lists

community wiki-pages

Engineers

Product mangers

Non-technical users

designers

Editors

non engineers may be reading what you write

think about how your writing will make sense to them


think about how the person reading's emotional investment

worried

angry

frustrated

try not to make others angry with your writing

"This approach wont work. Foo doesnt support Bar"


"I'm not sure if this approach will work"

it's good to remove uncertainty and clarify where everyone is coming from

don't speak in absolutes

there's a balance between being clear and direct and making sure there is room to negotiate meaning

"we need those updates soon"

who needs them

where are the updates

when is soon (never use "soon"!)

eg "I need it by Friday"

also helps you clarify when you need things by


"this thing is going to fail badly if we dont fix it in the short term"

dont assume the context

explain what is going to fail

why it is going to fail

when do we need to fix it by

sometimes its better to draw something 

diagrams can be very effective way to clarify bigger pictures

Tools

UML format diagrams:  plantuml

google docs

mermaid in gitlab

diagrams can be confusing

who is the author

why was it written

context sharing is important

let the reader know up front

"I [name] am writing this because X"

Read out loud what you are writing

forces you to make things shorter and use simpler language

helps with tone


LanguageTool

https://languagetool.org

like Grammarly

support for ~30 languages

browser plugin

google doc integration

it will alert when you are using passive voice

help you add in commmas

help with mispelling


Useful tools

- Outliners


Google Technical Writing One

https://developers.google.com/tech-writing/one

two hour course

free


Vale

https://vale.sh/


you dont have to write your comment where you are posting it

you can write it in google docs and where tools and available and then paste it into its final location


Tech News manual has a few tools:

https://meta.wikimedia.org/wiki/Tech/News/Manual#Writing_guidelines 

https://hemingwayapp.com/ 

https://splasho.com/upgoer6/

break sentences after periods, ands, ors

its more a practice than a tool

topic: some awesome subject

Why:

....

What:

.....

Bug


Remember:

Subject should be 50 characters or less

Separate body from subject

Use imperative mood ...


puppet repo has a commit template: 

https://github.com/wikimedia/operations-puppet/blob/production/.gitmessage 

git config commit.template .gitmessage

you just need to set it once per repo

https://mediawiki.org/wiki/Gerrit/Commit%20message%20guidelines 


templates are very helpful

it can be hard to explain

keep that in mind when writing and reading

writing "I think" a lot

it does help the tone, tempering/softening

could use "maybe", "perhaps", "i wonder", 

also a flag to yourself to check if its actually what you think

ambiguity could hide the lack of understanding

Simply "do this extremely difficult thing"

https://justsimply.dev/

https://css-tricks.com/words-avoid-educational-writing/