Плохая документация по коду? Независимо от того, Swimm сделает его более информативным и быстрым.

Традиционные системы управления документами подвели разработчиков программного обеспечения, и пришло время для нового пути.

Использует ли Swimm Docs-as-Code, чтобы предоставить разработчикам необходимую помощь?

Это самое последнее понятие или слияние?

Современный процесс разработки программного обеспечения — это странный возврат к прошлому.

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

С другой стороны, когда дело доходит до документации кода, мы продолжаем использовать одни и те же старые методы, ожидая других результатов.

Разработчики, безусловно, заслуживают большего, но как улучшить документацию как процесс?

Давайте поговорим об этом, уделив особое внимание Swimm, новой системе управления документацией/знаниями, которая поддерживает идею непрерывной документации.

Почему разработчики теряют надежду на документацию?

Прежде всего, почему мы вообще обсуждаем документацию?

Мы уже знаем, что оно имеет высокую воспринимаемую ценность.

Конечно, документировать сложно, но если мы все скинемся и все задокументируем, проблем не должно быть, верно?

Не совсем. Как вы увидите, проблема заключается в процессе, а не в индивидуальных усилиях и увлечениях.

Любое подлинное решение потребует большего, чем просто работа локтями.

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

Но страшилки всегда были одни и те же:

  • Нет соответствующей документации. Вместо этого вам советуют, что важнее быстрее получить больше функций, и что «отличный код документирует сам себя!»
  • Документов никогда не бывает достаточно, чтобы начать работу с новой кодовой базой. Когда вы спрашиваете о задаче, вас отправляют к документу со странным названием на корпоративном Google Диске.
  • Задания позиционируются как «высокая документация», однако это означает, что у них есть кладбище Confluence с устаревшей проектной документацией и ничего о том, как настроить и использовать внутренние инструменты разработки.
  • «Документирование новых конечных точек аутентификации пока не является приоритетом. Воспользуйтесь документами V1, которые у нас где-то висят, и попросите помощи в Slack».

Тысяча порезов бумагой означает смерть.

Вы бы поверили документации, если бы это повторилось в разных проектах?

Готовы ли вы из кожи вон лезть, чтобы писать и поддерживать качественную документацию, зная, что ее будет почти сложно найти, что она устареет через несколько месяцев, а ценный опыт, связанный с конкретным проектом, будет потерян из-за текучести кадров?

«Документация» — это не фигня

Вы можете создать сколько угодно инструментов поверх текущего процесса, но это не поможет.

Вот секрет, который большинство людей, ищущих решение, никогда не узнают.

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

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

Вот почему документация никогда не может быть единым объектом «Супермен», который после создания удовлетворяет все потребности в знаниях.

Вот почему новая система документации, используемая компаниями, не поможет вам в этом.

Форсирование проблемы в конечном итоге приводит к запутанной документации.

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

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

Что связывает нас с Swimm.

Swimm — Доверьтесь победе в документации

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

Они также имеют интерфейсы Slack и IDE (Jetbrains и VS Code), которые позволяют вам просматривать локальные предварительные просмотры ваших документов, даже если вы не подключены к Интернету.

Но прежде чем мы перейдем к Swimm, позвольте мне высказать собственное мнение:

  • Меня не интересует еще одно решение Notion или Confluence в сочетании с еще одним Bitbucket и Jira. Я устал от технологий, разработанных на основе нынешних способов работы с документацией в компаниях.
  • В целом мне нравится подход «Документы как код», однако…
    Для этого я могу просто использовать обычное, проверенное в боевых условиях решение ReadTheDocs. Он должен обеспечивать что-то дополнительное.
  • Ничто так не отталкивает меня, как привязка к поставщику.
  • Если мне нужно загрузить код непосредственно на серверы SaaS, мне может потребоваться сначала утвердить его в юридическом отделе, что может замедлить мои усилия по документированию и заставить меня задуматься, а стоит ли оно того. Так что это исключено.

Как Swimm справляется с этими требованиями? Вот некоторые из моих основных тезисов.

Как настроить плавание

Если вы хотите использовать Swimm, вы должны сначала создать учетную запись и подключить свой репозиторий GitHub.

Процесс прост, но в настоящее время он ограничен GitHub. Тем не менее, я считаю, что поддержка других платформ, таких как GitLab и BitBucket, уже в пути.

Получение приложения Swimm Github также технически необязательно, но я настоятельно рекомендую вам считать его таким же важным, как, скажем, использование строгого режима для разработки TypeScript.

Вы скоро поймете почему.

Политика конфиденциальности и безопасности Swimm превосходна. Они соответствуют SOC 2 и ISO27001, а ваш токен аутентификации GitHub и код никогда не передаются и не хранятся на серверах Swimm.

Приложение использует GitHub OAuth и требует доступа только для чтения репозитория, регулярной оценки изменений и сохранения созданной вами документации в отдельном каталоге .swm.

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

Когда документация связана с кодом, легко предоставить структурированную, целенаправленную документацию.

Первое, что меня поражает, это то, как вы пишете документацию в Swimm.

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

…или любой код, обнаруженный где-либо в нем. Можно использовать переменные, функции и даже полные фрагменты кода.

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

Документация — в IDE.

Итак… да. Swimm упрощает создание приличной документации, но это лишь временное решение, если мне все еще придется рыскать в тысячах разных мест, чтобы найти ее.

Что, если бы я мог держать документацию рядом со мной, пока я кодирую?

Без необходимости использовать Alt-Tab для Confluence, Wikis, GitHub и Slack?

Тем не менее, Swimm IDE Marketplace напоминает мне, что поддержка уже в пути.

Прекрасный!

«Автосинхронизация» Swimm

Написание надежной документации — это просто часть процесса.

Как вы гарантируете, что он всегда актуален?

Чтобы продемонстрировать, я вернусь в свою IDE и обновлю часть этого кода (например, изменю свойство timestamp на более удобочитаемую версию) перед его фиксацией.

В целом, Swimm предлагает более простой и многофункциональный подход, чем классические системы «документы как код».

Плейлисты делают обмен информацией легким и увлекательным.

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

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

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

И, как и в случае со стандартными документами Swimm, они автоматически синхронизируются и обновляются.

Эра непрерывной документации

Это подводит нас к концу этого обзора.

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

Речь идет о том, чтобы работать умнее, а не усерднее.

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

Swimm не идеален, но он ближе всего к пониманию того, как процесс приобретения знаний отличается для современной разработки программного обеспечения, а также как меняются его требования.

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

Swimm можно опробовать здесь.

Не забывайте подписываться на меня, чтобы оставаться позитивным.

Сайонара, увидимся в моем будущем посте.