Page MenuHomePhabricator

[Session] Improve your technical writing
Closed, ResolvedPublic


  • Title of session: Improve your technical writing
  • Session description:

Technical writing is an essential, but often overlooked, skill for effective software engineering. In this interactive workshop, we'll discuss techniques to improve our technical writing, and level up our abilities to explain, convince and inspire others.

We will evaluate and critique examples[0] of technical writing in Phabricator, IRC/Slack, code review comments and commit messages.

By the end of the workshop, you will be able to easily identify "code smells" in technical writing, know of simple ways to improve your writing, and feel more confident in your communication skills.

[0] We'll use example text (probably mostly mine 😭) with author's permissions and consent, along with some made-up examples.

Event Timeline

Below you may find the link attached that redirects the user to the corresponding Etherpad:

Small update:

  • I have slides (!). I'll share them here on Phab after the presentation
  • In the session, I'll present examples of unclear writing. For each example, we'll discuss how one could improve on the writing
  • We probably won't have time to collaboratively critique writing samples, but, let's see how the session goes
  • If you have some suggestions on how to improve technical writing, I'll be sure to make space for you to share your thoughts as well

See you soon! Also, please note that we will likely be in the Innovathens conference space, please look for an announcement on Telegram with details.

kostajh updated the task description. (Show Details)

Session Notes:

Improve your technical writing

Date & time: Sunday, May 21st at 9:30 am EEST / 6:30 am UTC
Wikimedia Hackathon 2023, Athens
Location: Technopolis Innovathens 1st floor

Relevant links


Presenter: @kostajh
Session coordinator: @Cstone


Kosta took a free two hour Google Technical Writing One course, recommended.

Why are people here

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

Communication is hard

technical communication is harder

writing can help with code smells

Take everything with a grain of salt

want to communicate better

Don't use passive voice

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

Write short and clear sentences

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

Avoid it, this, and that

it can be confusing what it and that is 

"I think this is a bad idea"

Use Lists

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

Use links and leave a paper trail

"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.

Organize and format your text

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

Consider your venue

in each space there are different ways to commuincate


shorter amounts of text, doesnt need to be formal


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



Google Docs

mailing lists

community wiki-pages

Consider your audience


Product mangers

Non-technical users



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




try not to make others angry with your writing

If you are not sure about something, let your reader know

"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

Who, where, when, what, why?

"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

Use diagrams

sometimes its better to draw something 

diagrams can be very effective way to clarify bigger pictures


UML format diagrams:  plantuml

google docs

mermaid in gitlab

diagrams can be confusing

Mystery Google Docs

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


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

two hour course



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:

semantic line breaks -

break sentences after periods, ands, ors

its more a practice than a tool

commit templates

topic: some awesome subject







Subject should be 50 characters or less

Separate body from subject

Use imperative mood ...

puppet repo has a commit template: 

git config commit.template .gitmessage

you just need to set it once per repo 

templates are very helpful

non native speakers

it can be hard to explain

keep that in mind when writing and reading

try not to be harsh

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

could use "I don't know if this works"

Simply is bad

Simply "do this extremely difficult thing"

@kostajh: Thanks for participating in the Hackathon! We hope you had a great time.

  • If this session / event took place: Please change the task status to resolved via the Add Action...Change Status dropdown.
    • If there are session notes (e.g. on Etherpad or a wiki page), or if the session was recorded, please make sure these resources are linked from this task.
    • If there are specific follow-up tasks from this session / event: Please create dedicated tasks and add another active project tag to those tasks, so others can find those tasks (as likely nobody in the future will look at the Hackathon workboard when trying to find something they are interested in).
  • In this session / event did not take place: Please set the task status to declined.

Thank you,
Phabricator housekeeping service