Twitter тред с советами по ведению документации.

Три важных пункта, которые я вынес лично для себя:
1. Организуйте периодическое ревью документации
2. Персонализируйте. Вопрос должен ставиться не "есть ли документация к этому компоненту", а "кому понадобится такой документ"
3. Отправляйте документы на ревью не только своим ближайшим коллегам, но и ЦА этих документов

#documentation

​Good documentation is foundational for implementing DevOps capabilities - State of DevOps says.

But writing good docs is hard... and what can you do, except hire a Tech writer?
Cry Try to write docs better.

Here are free technical writing courses by Google (and quick recap). I drive "good docs culture" (that happened historically) in my current job and find these courses really helpful in describing to teammates how docs should look.

Also, I found that already exist documentation style guides by Google and Microsoft so you don't need entirely reinvent the wheel, just a little part of it ;)

On the other hand, these style guides look very complicated, so to not be overwhelmed, just start from these highlights.

And if you need, more technical writing resources and reasons why docs should be and should be good - here.

P.S. Don't repeat my mistake - take these courses before start writing and reviewing docs on a regular basis, not in ~2 years after.

#documentation #culture

Do you prefer understandable diagrams to tons of text?

C4 model - describe principles for creating architecture diagrams and how to be sure that they will be useful and readable.

The site includes talk, which is so amazing, that I propose you spend 35min on it.

One of the mentioned tools in the talk is Structurizr. We start adopting that tool a few weeks ago and the final results look pretty nice.

And yes, Structurizr is more powerful than Mermaid, but do not work in plain markdown.

#documentation