#документация

Прикольно, как меняются технические аудиты.

Сейчас мы делаем технический аудит и план технического развития бизнесу, которому почти 30 лет. Десятки репозиториев на разных языках, большАя часть логики в сотнях хранимых процедур и триггеров в монолитной MSSQL базе.

За 4 недели архитектор смог разобраться на уровне, который раньше занял бы полгода минимум.

При этом, если раньше мы готовили PDF файлы и схемы, которые читали люди, то теперь мы собираем папку с анализом исходников, папку с анализом базы (один файл на хранимку или таблицу), и так далее. Все зависимости, вся логика проекта — в текстовых описаниях. Ну и файл с описанием, что мы делаем и для чего, конечно. Все это в гите, с контролем версий.

А дальше подключаем этот репозиторий к Claude code и задаем вопросы по проекту: «как устроена логика ценообразования», «на что повлияет изменение параметра Х», реестр рисков и так далее. Ответы проверяют живые инженеры — так мы оцениваем качество нашей базы знаний.

—

Если раньше мы оставляли пусть хорошо и с любовью написанные, но документы и делились пониманием в разговорах, то теперь мы как будто оставляем своего цифрового двойника, который будет продолжать отвечать на вопросы заказчика даже после окончания аудита.

Эту базу знаний будут использовать не только для этого рефакторинга, но и для онбординга новых специалистов.

—

Через 4 недели работы, мой архитектор взял 2 недельный отпуск. Мы дадим свои рекомендации и закончим аудит уже после его возвращения.

Скорость работы увеличилась в разы, но нам, людям, все ещё нужно время, чтобы новые знания уложились в голове. Нужно время, чтобы понимание проросло в нас. Слово «проросло» точно отражает то, что этот процесс нельзя ускорить усиленной работой. Можно только создать условия и не мешать. Раньше это происходило естественно, теперь нужно специально делать перерывы.

—

Раньше я гордился тем, какие четкие, ясные, красивые диаграммы сервисов мы рисуем. Теперь их заменили полностью автоматизированные mermaid схемы. Генеральную схему всего бизнеса таким образом мы пока не нарисовали, она получатся совершенно неудобоваримая. Это ограничение технологий или отражение внутренней сложности бизнеса? Пока что ее нет и у нас в голове, так что это открытый вопрос.

—

Делюсь тремя файлами: Claude_md — общие правила игры для модели, а ещё файлы с целями и принципами этого аудита.

Диалог уровня Тарантино из недавно рассекреченных документов судебного дела о приватности в фейсбуке. Special master — эксперт назначенный судом, расспрашивает двух супер-опытных инженеров фейсбука под присягой (один из них уровня директора) про то, как фб хранит и обрабатывает данные.

Мой вольный перевод исходника.

Эксперт: у нас ведь есть блок-схема? Вы ведь когда прогаете — наверняка у кого-то должна быть схема, где эти данные хранятся?

Зарашоу (engineering director): у нас немного странная инженерная культура, в сравнении с другими компаниями, мы генерируем довольно мало документации в процессе разработки. Получается, исходный код — это и есть документация.

Эксперт: то есть нужно смотреть в исходный код, чтобы понять... я имею в виду...

Зарашоу: честно говоря, я тоже был в ужасе, когда только устроился на работу.

Дорогой Игорь из нашего чата @ctodailychat делится опытом:

☞
В нашей команде мы перешли на FAQ first development. Если хочется запилить фичу, то первым делом пишется пресс-релиз и/или FAQ который впоследствии становится спекой.

Бенефиты:
- Фичи стали более продуманными и формулируются через value которые они несут;
- Улучшилась командная коммуникация. FAQ всегда под рукой и на вопросы можно ссылаться. Во время дизайн сессий возникает множество вопросов которые пополняют документ;
- Сейлы знают что они продают и умеют правильно питчить фичи;
- Программисты понимают, что важно, а где бессмысленная дрочка.

——

Классный прием!

ААА, на сайте документации докера есть переключатель на черную тему

OpenSSL - один из самых важных IT-проектов, на нем держится практически все шифрование. После недавних адских ошибок безопасности они улучшили ситуацию с разработкой, но вот с документацией и UX ситуация все ещё аховая.

Хорошая порка: https://jameshfisher.com/2017/12/02/the-sorry-state-of-openssl-usability.html

Apple обновил свой whitepaper (техническую статью) про безопасность в iOS, добавил информации по iOS 10.

Для неторопливого чтения, качественные 70 страниц A4: https://www.apple.com/business/docs/iOS_Security_Guide.pdf

У каждой большой корпорации и Open-Source сообществ есть свои языки документации. Мне ближе всего язык FreeBSD и PostgreSQL — краткий и в то же время очень четкий. Microsoft любит чуть по-длинеее, но легко читаемый.

У Эпл очень плотный текст, его приходится читать медленно и внимательно, иначе упустишь важные детали. Мне это кажется минусом — совсем не стараются, чтобы можно было быстро просмотреть и составить план действия. Сиди читай, как художественную литературу. В их защиту скажу, что именно эта статья даёт очень хороший обзор всего богатства и сложности безопасности в современных мобильниках. Достойное чтение.

Очередная отличная статья про программирование.
И опять от девушки!

На этот раз про Rust (kind of). Как вы могли заметить, я коллекционирую хороший технический сторителлинг.

В статье меня зацепило, что многие люди не слышало о strace. Возвращаясь к handbooks. Хороший systems handbook как раз перечисляет основные утилиты и подходы, с которыми необходимо быть знакомым. Мне не кажется хорошей ситуация, когда нет единой отправной точки, общепринятого теоретического минимума и знание рассыпано мелким зерном по serverfault и презентациям.

Ну, довольно старческого брюзжания на сегодня; наслаждайтесь классными картинками в статье.

http://jvns.ca/blog/2016/09/11/rustconf-keynote/

У меня есть личная неприязнь к MySQL. Причина не в функциональных недостатках - это исключительно мощный софт; многие крутые технари делают базы именно на нем.

Причина - в документации. В этом неумении сформулировать мысль не растекаясь на 10 страниц. В неумении отделить один раздел от другого.

Подростком я читал The FreeBSD Handbook. Это пример идеального технического документа своего формата. Рекомендую почитать, даже если вы не технарь. Просто оцените лёгкость слова и качество подготовки текста.
https://www.freebsd.org/doc/handbook/

Документация PostgreSQL - из той же лиги.
https://www.postgresql.org/docs/9.5/static/index.html

Интересно, что любовь к элегантности и красоте не обязательно ведёт к коммерческому успеху. И как прекрасно, что есть исключения вроде Apple, где они сочетаются.

Навеяно вот этим списком свежих критических уязвимостей MySQL.
http://legalhackers.com/advisories/MySQL-Exploit-Remote-Root-Code-Execution-Privesc-CVE-2016-6662.html