Советы, как сделать документирование вашей работы интересным

В мире, где все сжато в 30-секундные тиктоки/ролики IG..

Чтение и понимание документации становится настоящим навыком. Это скучно, требует вашего пристального внимания и может стать супертехничным. В то же время это также может помочь вам выделиться

— Из Твиттера

Документирование часто считается скучным, трудоемким и трудным аспектом нашей работы. Но это важно!

В этом ежедневном дайджесте мы рассмотрим некоторые руководства, инструменты и приемы, чтобы снова сделать написание и чтение документации интересными!

Проблемы с документацией данных? Вот основа — в тот день, когда старый член команды данных решил уйти, Прукалпа был контужен. Тем более, что у члена команды был весь контекст данных, которые он использовал. По ее собственным словам: Когда я проснулась на следующее утро, я помню, как дала себе обещание — никогда больше я не дам ни одному человеку возможность поставить нас в такое уязвимое положение. Этот инцидент ознаменовал начало Проекта сборочной линии в Atlan — инициативы, направленной на то, чтобы сделать группы обработки данных максимально гибкими и устойчивыми — и тем самым способствовать развитию культуры, ориентированной на документацию.

Затем прочитайте Тревор-Индрек Ласн руководство по написанию и публикации красивой интерактивной документации по коду с помощью инструмента DocZ. DocZ на базе Gatsby невероятно быстр и позволяет создавать и использовать настоящие настраиваемые темы. Он также поставляется со встроенной поддержкой TypeScript.

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

Конечно! Когда дело доходит до написания документации, Markdown фактически является инструментом для разработчиков. Тем более, что вы можете использовать расширения VS Code, чтобы сделать редактирование намного быстрее. От добавления предварительного просмотра, сочетаний клавиш, автоматического предварительного просмотра до использования PlantUML и вставки изображений и смайликов — вот пять расширений VS Code, которые сделают ваш Markdown более эффективным.

Кроме того, вы можете выделить свой код в Markdowns с помощью Remarkables — веб-компонента, помогающего красиво отображать код, а также позволяющего настроить пользовательские синтаксические анализаторы для динамического выделения кода. Вот практическое руководство от Дэвида Дал Буско, чтобы сделать ваш код Markdown замечательным.

Нужно больше вдохновения, чтобы использовать код в документации? Виктория Дрейк показывает нам, как автоматизировать README профиля GitHub, создав динамический файл Markdown с помощью Go и GitHub Actions.

Если есть список Лучшие редакторы Markdown, bshelling рекомендует добавить в него Visual Studio Code.

Чтобы улучшить качество документации для LWC, используйте библиотеку JSDoc, как показывает в своем рассказе Себастьяно Вирк.

Все еще чувствуете, что документирование кода отнимает много времени? Джеймс Бриггс показывает нам, как создать инструмент автоматического документирования для любого проекта Python. Не пропустите его Auto-docs for Python.

Говоря о Python, вы можете начать писать строки документации Python, следуя руководству Луи де Брейна. Или перейдите к Yong Cui, посвященным рекомендациям по определению строк документации функции.

Трудно игнорировать Джулию, особенно когда речь идет о Python. Используйте руководство Emmett Boudreau, чтобы автоматизировать документацию Julia с помощью Documenter.jl.

Знаете ли вы, что Apple значительно упростила написание документов с помощью DocC — инструмента для написания документации из Xcode? Ознакомьтесь с руководством Амита Саманта, чтобы получить первый взгляд на многообещающий новый инструмент Apple. Он также написал второе руководство, чтобы показать, как мы можем поделиться нашей документацией со всем миром, разместив документацию DocC в Интернете и синхронизировать ее между веб-сайтами и кодовыми базами.

Если вы работаете с AWS, Аллен Хелтон расскажет нам, как правильно документировать архитектуру, управляемую событиями, с помощью Async API Spec. Благодаря Async API мы можем четко указать, каковы схемы наших событий, каковы различные каналы, какие события потребитель может публиковать или на которые может подписаться, и какая служба/среда (EventBridge или WebSocket) необходима для публикации или подписка есть. В противном случае, если вы занимаетесь смарт-контрактами, см. Как документировать код надежности без особых усилий.

Все еще лень писать документацию? Пусть ИИ напишет это за вас. Ханби Ли и ее команда в Mintlify представили AI Doc Writer, расширение VS Code, которое стремится автоматизировать документацию, позволив инструменту позаботиться об этом. Просто выделите код и нажмите Command + . на своем Mac, чтобы сгенерировать документацию для функции. Я протестировал его на одной из моих функций, созданных GitHub Copilot, и результаты были приличными.

Еще не переехали? Ее команда сделала еще одно расширение VS Code под названием Генератор каркаса Docstring для упрощения вашей документации.

Вот и все. Спасибо за прочтение.