Я на днях спрашивал: выкладывать ли "велосипед" на GitHub? Сомневался, прикидывал, что "кастрировать".

Вобщем решился.

И начал готовить код к публикации. Три часа ушло на то, чтобы вычистить лишнее: другие движки БД, сервер очередей, A/B-тесты, фингерпринты, кэширование. Всё аккуратно удалить, чтобы не оставить "следов". Как хирург, который удаляет аппендикс, а потом проверяет, не забыл ли он что-то внутри.

А потом я открыл документацию. У меня есть полная документация на предыдущую мажорную версию. Текст с примерами. 121 страница. Я её писал. Для себя. Для команды. Для проектов. И теперь я понимаю, что для демо-версии нужно переписать её заново. Потому что удалённые фичи - это не просто "убрать описание". Это перестроить логику объяснения. Это пересмотреть примеры. Это понять, что я вообще хочу показать человеку, который скачает мой код.

Итого, по моим прикидкам, мне предстоит написать 87 страниц маркдауна. Страниц. Маркдауна. 87!

Я их ещё не написал. Они только впереди.

И вот я сижу и думаю: я же хотел просто код выложить. Ну, там readme написать пару абзацев. А тут - 87 страниц. Это не "readme". Это "readme" в квадрате куба. Это книга. Только без издательства.

И самое забавное: эту документацию никто, скорее всего, не прочитает полностью. Но если я её не напишу - те, кто всё-таки откроет код, будут проклинать меня. И мою экосистему. И мои "велосипеды". С другой стороны - 87 страниц документации - это же готовый контент. Можно разбить на посты. На статьи. На серию "Как устроен ваш велосипед изнутри". Вариантов масса.

Но сначала, правда, их надо написать, ну или адаптировать если в исходном тексте подходяще описано.

Теперь я знаю, каково это - быть техническим писателем. Это не просто "написать текст". Это разложить по полочкам весь свой мозг. Так, чтобы другой человек мог в нём разобраться. Без твоих объяснений. Без твоих звонков. Просто открыл файл и понял.

В общем, когда я закончу, я выложу репозиторий. С урезанным кодом. С 87 страницами документации. И со смешанными чувствами: с одной стороны - страшно, с другой - любопытно.

А вы документируете свой код? Пишете по 80+ страниц? Или считаете, что "код - это документация"?

Я теперь точно знаю: код - это код. А документация - это отдельная вселенная. И она требует времени. Много времени.

Ну, или наймите технического писателя. Я теперь понимаю, за что им платят деньги.

Сайт https://tzlab.pro