My colleague John Greene has a gift few writers in the world of technology possess: He knows how to talk about complex software in words non-experts will understand. Better yet, he regularly helps spread the message as to why that’s important.
In a course he’s developing about the open source philosophy of making your code publicly available, John explains why open-source projects need lots of good documentation. First, it helps your users onboard without bombarding a team of busy engineers, often volunteers, with questions. Second, it makes it clear to potential contributors under which conditions they can and should engage with the project. If you want to support with marketing or lines of …
My colleague John Greene has a gift few writers in the world of technology possess: He knows how to talk about complex software in words non-experts will understand. Better yet, he regularly helps spread the message as to why that’s important.
In a course he’s developing about the open source philosophy of making your code publicly available, John explains why open-source projects need lots of good documentation. First, it helps your users onboard without bombarding a team of busy engineers, often volunteers, with questions. Second, it makes it clear to potential contributors under which conditions they can and should engage with the project. If you want to support with marketing or lines of code, where do you start?
At one point, John sums up this principle in a nutshell, and it applies well outside the casings of our computers: “The best defense against misunderstanding is communication.” If a project wants to prevent user or contributor errors, the answer is not more customer support. It’s better documentation. If you’re not sure whether your colleague understood what you expect from them, the way to make sure is to follow up and ask again. And if you don’t like going to museums, it’s probably best to tell your partner that instead of making up excuses.
Communicating more, clearly, and ahead of time may feel like an “offense-beats-defense” strategy. But it’s not offense. It’s cooperation. You don’t have to do it aggressively. It’s enough to do it kindly, without hoopla. Just like good documentation: It’s there. It helps. That’s it.
Let’s all be purifiers and clear the air before it starts smelling.
Nik
Niklas Göke writes for dreamers, doers, and unbroken optimists. A self-taught writer with more than a decade of experience, Nik has published over 2,000 articles. His work has attracted tens of millions of readers and been featured in places like Business Insider, CNBC, Lifehacker, and many others. Nik has self-published 2 books thus far, most recently 2-Minute Pep Talks. Outside of his day job and daily blog, Nik loves reading, video games, and pizza, which he eats plenty a slice of in Munich, Germany, where he resides.