Как выстроить разработку внутренней документации
Игорь @i_tsupko спрашивает в чате @docsascode:
Проблема: есть пара-тройка человек, которые пополняют внутреннюю базу знаний. И каждый тянет одеяло на себя, не могут договориться о том как структурировать доки, как делать меню, навигацию и прочее.
Как договориться? В программировании для этого есть фреймворки и паттерны. А с русским языком как быть? Он ж не компилируется и автотесты не напишешь.
Что важно в документации:
— Структура и читаемость — чтобы юзер мог это брать и юзать на своем уровне компетенций.
— Ненагруженный, неформальный язык и минимум формализма.
— Важнее наличие хотя бы паршивой, верхнеуровневой, но хорошо структурированной доки (а-ля вот эта задача решается примерно по таким шагам, копать туды) но раньше, чем хорошо проработанной, но позже.
— Важно, чтобы дока внедрялась и юзалась. Важнее всего и даже текста.
У вас тоже это болит? Знаете решение? Приходите в @docsascode, обсудим.
Игорь @i_tsupko спрашивает в чате @docsascode:
Проблема: есть пара-тройка человек, которые пополняют внутреннюю базу знаний. И каждый тянет одеяло на себя, не могут договориться о том как структурировать доки, как делать меню, навигацию и прочее.
Как договориться? В программировании для этого есть фреймворки и паттерны. А с русским языком как быть? Он ж не компилируется и автотесты не напишешь.
Что важно в документации:
— Структура и читаемость — чтобы юзер мог это брать и юзать на своем уровне компетенций.
— Ненагруженный, неформальный язык и минимум формализма.
— Важнее наличие хотя бы паршивой, верхнеуровневой, но хорошо структурированной доки (а-ля вот эта задача решается примерно по таким шагам, копать туды) но раньше, чем хорошо проработанной, но позже.
— Важно, чтобы дока внедрялась и юзалась. Важнее всего и даже текста.
У вас тоже это болит? Знаете решение? Приходите в @docsascode, обсудим.