DocOps
1.73K members
6 photos
1 file
249 links
DocOps — это как DevOps, только про документацию.

Пишу про документацию и управление знаниями. Знакомлю с инструментами и практиками.

Автор всегда рад пообщаться, пишите @Nick_Volynkin


Чат: @docsascode
Download Telegram
to view and join the conversation
Как сделать так, чтобы документация не болела?

Мы с Семёном @factorized провели сегодня митап про документацию на Highload++ Siberia. Поговорили о типичных проблемах разработки, которые можно решать с помощью документации. Конечно, всё законспектировали. Вот, держите: https://github.com/docops-hq/conf/blob/master/highload/19/siberia/docs.md

Если вы были на митапе или вам просто интересна эта тема — давайте общаться дальше, заходите в чат @docsascode.
А вот пара фотографий с митапа.
​​Из статьи Почему Интернет до сих пор онлайн?:

Протокол BGP — Border Gateway Protocol, впервые был описан в 1989 году двумя инженерами из IBM и Cisco Systems на трёх «салфетках» — листах формата А4. Эти «салфетки» до сих пор лежат в главном офисе Cisco Systems в Сан-Франциско как реликвия сетевого мира.

А вот фото этих документов, источник: https://twitter.com/kazumasaikuta/status/1121568522495123456
​​Курс по документированию REST API на русском языке.

Тут случилось что-то невероятное. Курс Тома Джонсона по документированию REST API переведён на русский язык. Денис Старков сделал это сам, один, за полгода работы.

Оригинальный Documenting APIs: A guide for technical writers and engineers — наверное, самый полный и полезный открытый курс по документированию. Он рассчитан на технических писателей, разработчиков и студентов. Для техписателей этот курс — точка входа в документирование кода и API, очень интересную область работы, за которую ещё и неплохо платят. Разработчики из этого курса научатся структурировать информацию и понятно описывать свой код и API.

Читайте переведённый курс по документированию REST API, рекомендуйте его коллегам, ставьте звёзды репозиторию. Шлите пуллреквесты с правками, наконец. :)
Можно ли превратить создание документации в процесс.

На конференции #CodeFestX мы проводили квартирник про DocOps и документацию в целом. Рассказывали, как внедрять хорошие практики и процессы документирования. Я делился опытом внедрения DocOps и работы над документацией в Plesk, а Семён — опытом своей компании documentat.io, которая аутсорсит разработку документации.

Смотрите видео, шлите обратную связь (@factorized и @nick_volynkin), пишите автотесты на доки. :)

https://www.youtube.com/watch?v=fMcyiVju9Tg
Инструкция к Palantir Gotham.
В сеть утекла техническая документация к сервису для поиска данных о гражданах, который использует полиция и спецслужбы США. Сервис называется Palantir Gotham. Документация конкретно пользовательская, писали не для отчётности. В начале документа — «шпаргалки», четкие пошаговые инструкции со скриншотами. Потом более подробные инструкции, описания конкретных элементов интерфейса и сценариев.

Документация в PDF и plain text: https://www.documentcloud.org/documents/6190005-PALANTIR-Guide.html
Исходная статья: https://www.vice.com/en_us/article/9kx4z8/revealed-this-is-palantirs-top-secret-user-manual-for-cops
Про статью узнал из поста в @addmeto.

Приходите обсуждать в чат @docsascode. Тема этически сложная, давайте обойдем стороной холивары о политике и обсудим именно артефакт документации.
Отличный пост про docs as code и конкретно Sphinx/reST.

Репост из чата @docsascode
Forwarded from Lejbron
Коллеги, хотел бы поделиться с вами своей статьей на тему автоматизации процесса сборки сайта с документацией. Это мой первый опыт как полноценной работы в роли технического писателя, так и в написании подобного рода статей, буду рад критике!
https://habr.com/ru/company/youla/blog/459640/
DocOps-митап начинается с доклада о том, как вести репозиторий с документацией. Рассказывает Константин Валеев, сотрудник Ростелекома и один из авторов Foliant.
​​Классная идея, которую я только что узнал из доклада — это release notes для самой документации. Обновили раздел А, переписали документ Б. Обязательно попробую. Пока что у нас это только в сообщениях коммитов есть, но отдельный документ может быть интересен сам по себе.

Всё остальное из этого прекрасного списка мы (в docs.plesk.com) уже делаем сами и всем рекомендуем. :)
​​Вот три примера кода:
Отчётный ролик про нашу #knowledgeconf2019
Forwarded from KnowledgeConf Channel
KnowledgeConf — самый полезный эксперимент Онтико этого года, и сегодня мы хотим еще раз окунуться в ту атмосферу идеального knowledge sharing’а, которая царила на конференции.
Смотрим отчетный ролик и записи лучших докладов и вас приглашаем 📺
​​Угадайте, что имели в виду авторы вакансии?
Пишите в @docsascode.
​​Документация шаблонизатора Liquid — это просто песня.