У Etsy очень интересный подход к поддержанию документации в актуальном состоянии, советую ознакомиться. Лично мне подход очень нравится концептуально, однако в качестве long-term солюшна я не вижу это удобным и растущим вширь, но что-то да можно почерпнуть:

https://codeascraft.com/2018/10/10/etsys-experiment-with-immutable-documentation/

TL;DR: Все документы делятся на два куска “why-docs” и “how-docs” и чуваки пришли к выводу, что “how-docs” меняются куда чаще и запилили слак-reactji (типа emoji) и бота, через которого можно посмотреть советы из чата тегнутые соответствующим смайликом и которые относятся к задаваемому вопросу. Красиво и современно — да, а вот насколько это удобно, долговечно и scalable сказать сложно.

#article #en