Привет!

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

Итак, с самого начала взаимодействия с проектом будем работать по всем правилам docs as code:

1. Откройте CMD и перейдите в папку проекта. Сделайте это с помощью уже знакомой команды cd путь_к_папке;
2. Проверьте состояние проекта. Выполните команду git status. Что нужно смотреть в статусе репозитория? То, что вы находитесь в нужной ветке (main) и что у вас нет незафиксированных изменений;
3. Обновите репозиторий. Для этого выполните команду git pull. Эта команда забирает актуальную версию ветки из оригинального репозитория на наш компьютер. Сейчас таких изменений нет, но мы будем следовать правилам;
3. Каждая новая задача (а перед нами стоит задача добавить первый файл) должна выполняться в отдельной ветке. Создайте новую ветку task-1-add-file, отколов её от ветки main. Для этого выполните команду git branch task-1-add-file;
4. Вы откололи новую ветку, но git status покажет, что вы до сих пор находитесь в ветке main. Чтобы переключиться на рабочую ветку, выполните команду git switch task-1-add-file;

Теперь, когда мы находимся в рабочей ветке, можно приступать к созданию первого файла. В папке проекта создайте файл index.md. Это главная страница нашей документации. Я не буду регламентировать её содержание, напишите здесь то, что считаете нужным. Мой портал будет посвящён контенту канала Parawriter, поэтому я напишу здесь приветственный текст наподобие первого своего поста в телеграме.
Единственное условие — используйте разметку markdown. Синтаксис маркдауна очень прост и я не буду останавливаться на этом подробно, ведь в интернете есть много шпаргалок и руководств (например, вот), а ещё вы можете почитать мини-курс у Лены на канале.

С маркдаун-файлами удобно работать в специальном текстовом редакторе, и я опять настоятельно рекомендую скачать Visual Studio Code.

После создания нового файла нам нужно отправить его на сервер:

1. Вернитесь в CMD и снова выполните команду git status. Система показывает, что в вашем проекте есть изменения:

C:\Users\User1\parawriter\parawriter_docs>git status
On branch task-1-add-file
Untracked files:
  (use "git add <file>..." to include in what will be committed)
        index.md

nothing added to commit but untracked files present (use "git add" to track)

Перед тем, как создать коммит, нужно сообщить гиту, какие изменения вы хотите зафиксировать в коммите. Для этого используется команда git add. Так как мы собираемся зафиксировать все изменения, выполните команду в таком виде: git add .;

2. Теперь файл index.md проиндексирован. Для создания коммита выполните команду git commit -m "краткое описание изменений":

C:\Users\User1\parawriter\parawriter_docs>git commit -m "Добавил новый файл index.md"
[task-1-add-file df62424] Добавил новый файл index.md
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 index.md

Система сообщает о том, что изменения зафиксированы.

3. Нам нужно отправить коммит на сервер. Для этого выполните команду git push. Так как вашей рабочей ветки ещё нет на сервере, используйте команду с флагом set-upstream: git push --set-upstream origin task-1-add-file. Это нужно только для первого обновления, все последующие обновления ветки можно будет проводить командой git push без флага;

Поздравляю! Наш файл index.md отправился на сервер. Нам осталось создать пул-реквест и слить рабочую ветку и ветку main, чтобы обновить проект.

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

P.S. Если возникают сложности или появляются вопросы, приходите в комментарии)

#практика #docsascode

Привет! Сегодня мы создадим пул-реквест и поговорим о ревью задач.

Немного отдохнём от командной строки и поработаем с интерфейсом гитхаба.

Откройте репозиторий в гитхабе. Теперь, если вы раскроете список веток (кнопка слева над файлами репозитория, на кнопке отображается название текущей ветки main), вы увидите рабочую ветку task-1-add-file. Переключитесь на неё: в списке файлов появился новый файл index.md. Это значит, что изменения успешно добрались до сервера.

Чтобы провести ревью, а потом влить внесённые изменения в проект, нужно создать запрос на слияние веток: Pull request.
1. В верхнем меню выберите пункт Pull requests. Страничка пока пустая, потому что мы не создали ни одного запроса;
2. Нажмите зелёную кнопку New pull request;
3. В разделе «Compare changes» выберите ветки:
В поле base нужно добавить ветку main, а в поле compare — ветку task-1-add-file.
Гитхаб проводит проверку возможности слияния и выносит вердикт: Able to merge. Значит, всё хорошо, конфликтов не обнаружено, можно создавать пул-реквест.
4. Найдите зелёную кнопку Create pull request и нажмите на неё;
5. Придумайте название и описание пул-реквеста: заполните поля Add a noscript и Add a denoscription. Обычно в компаниях разработаны правила наименования пул-реквестов, но мы с вами не в обычной компании) Поэтому предлагаю придерживаться простой рекомендации: название должно кратко отражать суть задачи, а описание — подробности вносимых изменений.
Я назову пул-реквест «Добавление первого файла», а в описании расскажу, что именно я сделал: «Создал и добавил новый файл index.md».
6. Ещё раз нажмите кнопку Create pull request. Поздравляю, запрос создан!

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

Слиянием мы займёмся чуть позже, а пока я предлагаю выполнить небольшое домашнее задание. Да, здесь опять нужно вернуться к командной строке.
Что нужно сделать
Внесите изменения в файл index.md и отправьте эти изменения на сервер.
Подсказка
Всю работу над задачей мы проводим в одной ветке. Если в процессе ревью вы получили правки, то вносить их нужно в той же рабочей ветке, а потом по уже знакомому пути отправить изменения на сервер (проиндексировать изменения → создать коммит → отправить коммит). Если всё сделано правильно, ваш новый коммит попадёт в уже созданный пул-реквест.
Ожидаемый результат
Файл index.md изменён, в пул-реквесте на вкладке Commits отображаются два коммита.

Я желаю вам удачи! По всем вопросам приходите в комментарии!

#практика #docsascode

Привет!

Как успехи с домашним заданием? Надеюсь, у всех получилось внести новые изменения в файл index.md

Сегодня мы с вами выполним запрос на слияние и вольём рабочую ветку task-1-add-file в ветку main
Представим, что ревьюер принял вашу задачу и дал добро заливать ваши изменения в проект.

1. Откройте пул-реквест в гитхабе и промотайте вкладку Conversation до блока с подтверждением запроса;
2. Найдите зелёную кнопку Merge pull request и нажмите её.
3. Нажмите кнопку Confirm merge;
4. Гитхаб автоматически вольёт ваши изменения в ветку main и сообщит вам о том, что всё прошло успешно: «Pull request successfully merged and closed».

Поздравляю! Теперь ваши изменения находятся в ветке main.

В начале курса я обещал, что всё будет просто и гладко, как на бумаге. Но ходить нам потом придётся по оврагам, поэтому я должен вас об этих оврагах хотя бы предупредить.
Не всегда слияние веток проходит в два счёта. Бывает, что работа ведётся параллельно в одних и тех же файлах, и тогда изменения в двух разных ветках начинают конфликтовать друг с другом. При попытке слить такие ветки возникают конфликты, которые приходится решать. Иногда решение конфликтов выливается в муторный и удручающий процесс. К этому нужно быть готовым, но, к счастью, это тема больше касается практики работы с git и находится за рамками нашего весёлого курса по docs-as-code:)

Поэтому я вас поздравляю с простым и приятным merge pull request без конфликтов и проблем и приглашаю к следующему этапу организации docs-as-code — настройке сборки и публикации документации.

#практика #docsascode

Привет!
Что ж, мы отлично поработали на этой неделе: создали свой репозиторий, научились работать с гитом, написали первый документ в маркдауне.

Сейчас наш проект состоит из одного файла index.md
Мы можем добавить ещё несколько документов (сколь угодно много файлов name.md), и да, мы обеспечили надёжное хранение наших данных с возможностью отслеживать версии и контролировать вносимые изменения. Но как же нам пользоваться написанной документацией? Конечно, мы можем открывать превью любого файла прямо в гитхабе, только это неудобно и непрактично. Нам нужно придумать, как сформировать из имеющихся исходников структурированную и дружелюбную систему документации.
На помощь приходят статические генераторы. SSG (static site generators) — это программы, которые конвертируют размеченные файлы в html-страницы и собирают из них статический веб-сайт, который можно опубликовать на любом хостинге в интернете. Статический сайт — это отличный вариант для представления документации. Мы можем настроить процесс таким образом, чтобы при каждом обновлении ветки main в нашем репозитории запускалась конвертация markdown-файлов в html и пересобирался сайт с документацией.

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

В рамках нашего курса по docs-as-code мы будем использовать генератор MkDocs, а точнее, тему material генератора MkDocs.

Уже в следующем посте мы установим генератор и попробуем собрать локальную версию нашей доки. А пока немного предлагаю немного насладиться сентябрьской субботой (надеюсь, она у вас солнечная) и отдохнуть от рабочей недели 🍂

P.S. Давайте соберём 40 птичек в реакциях к этому посту, и я расскажу увлекательную историю про мое первое знакомство со статическими генераторами. Старый добрый интерактив 🕊

#практика #docsascode

Привет!
Перед тем, как настраивать наш сайт с документацией и делать его красивым/удобным/эргономичным, нужно снова выполнить небольшую домашнюю работу.

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

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

Например, у меня сайт с обучающими материалами, сложенными в два основных раздела: «Онбординг технического писателя» и «Docs-as-code для самых маленьких». Структура сайта будет выглядеть так:

Главная страница  // файл index.md
├─ Онбординг тех.писателя // файл onboarding.md
│  ├── Первый урок // файл onboarding/lesson_1.md
│  ├── Второй урок // файл onboarding/lesson_2.md
│  ├── <...>
│  └── Последний урок // файл onboarding/lesson_last.md
└─ Docs-as-code для самых маленьких // файл docs_as_code.md
   ├── Первый урок // файл docs_as_code/lesson_1.md
   ├── Второй урок // файл docs_as_code/lesson_2.md
   ├── <...>
   └── Последний урок // файл docs_as_code/lesson_last.md

Если у вас творческий кризис, не переживайте! Я разработал дефолтную схему, чтобы можно было продолжить курс:

Главная страница  // файл index.md
├─ Озёра России // файл lakes/index.md
│  ├── Онежское озеро // файл lakes/onega.md
│  ├── Ладожское озеро // файл lakes/ladoga.md
│  └── Байкал // файл lakes/baikal.md
└─ Реки России // файл rivers/index.md
   ├── Свирь // файл rivers/svir.md
   ├── Нева // файл rivers/neva.md
   └── Ангара // файл rivers/angara.md

В папке docs проекта создайте папки lakes и rivers, внутрь которых сложите md-файлы озёр и рек. В сами файлы добавьте краткие описания объектов (не забудьте разметить их с помощью маркдауна). Также в папках lakes и rivers создайте два главных файла разделов, которые будут называться index.md (да, тоже индекс.мд, только вложенные в папки разделов). Внутри можете написать какой-нибудь обобщающий текст по своему усмотрению.

Не забудьте, что все изменения мы делаем по классическому флоу с помощью гита (нужно отколоть новую ветку task-3-add-files, закоммитить изменения, отправить их на сервер, создать и пулл-реквест и влить изменения в main).

Фух, поздравляю, теперь мы готовы оформлять сайт! Если у вас всё получилось, ставьте рукопожатие в реакциях к этому посту 🤝

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

#docsascode #практика

Привет!

Сегодня мы настроим конфиг нашего сайта — mkdocs.yml
В нашем проекте уже есть этот файл, и пока что он состоит только из одной записи:

site_name: Parawriter docs

Остальные настройки добавляются аналогично в формате ключ: значение.

Что мы можем и должны прописать в конфиге?

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

Я долго думал, как уместить в один пост всё многообразие настроек сайта. И придумал:
Я подготовил шаблон конфига с самыми используемыми настройками. Каждому параметру дан поясняющий комментарий. Некоторые настройки отключены: для их включения просто удалите символ # в начале нужной строки. Чтобы отключить какую-нибудь активную настройку, наоборот, добавьте символ # в начало нужной строки.
Вы можете поиграться с параметрами, включая и отключая их и проверяя результат в локальной сборке.
Также в конфиг добавлены файлы из дефолтной схемы доки, которую мы обсуждали в прошлый раз. Если вы разработали свою структуру сайта, смело правьте раздел nav в конфиге, только будьте внимательны и следите за отступами и вложенностью страниц.
Подробное описание настроек конфига можно посмотреть тут.

Итак:
1. Скачайте конфиг из этого поста;
2. Добавьте его в свой проект (удалив при этом старый конфиг);
3. Настройте на свой вкус;
4. Приведите настройки nav в соответствие со своей структурой. Убедитесь, что все md-файлы проекта добавлены в конфиг;
5. Соберите доку локально с помощью команды mkdocs serve и убедитесь, что всё работает;
6. Отправьте изменения на сервер (не забываем, что все эти действия нужно производить в новой рабочей ветке по нашему git-флоу)

Поздравляю! Наш проект теперь почти готов!

В следующий раз мы займёмся, наверное, самым сложным — настройкой публикации сайта на github pages.

А если вы столкнулись с трудностями — добро пожаловать в комментарии!

P.S. Друзья! Если вы используете предложенную мной структуру про озера и реки, обратите внимание на изменения структурной схемы в прошлом посте.

#docsascode #практика

Привет!

Сегодня мы проведём последний урок курса «Docs-as-code для самых маленьких» и настроим CI для нашего сайта с документацией.

CI — это процесс непрерывной сборки и деплоя программного продукта. Docs-as-code подразумевает использование лучших практик работы с кодом, и потому мы попробуем настроить автоматические сборку и деплой сайта с документацией, которые будет запускаться при каждом обновлении ветки main.

1. Откройте CMD и перейдите в папку проекта с помощью команды cd;
2. Создайте новую рабочую ветку (этот процесс уже описывался в прошлых уроках и должен быть хорошо вам знаком);
3. Откройте папку с проектом через проводник;
4. Создайте новую папку `.github`в корне проекта;
5. Внутри папки .github создайте папку workflows;
6. Внутри папки workflows создайте новый файл ci.yml;
7. Откройте файл ci.yml с помощью VS Code или другого редактора;
8. Скопируйте текст ниже и вставьте его в файл ci.yml:

name: ci
on:
  push:
    branches:
      - main
permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: 3.x
      - uses: actions/cache@v2
        with:
          key: ${{ github.ref }}
          path: .cache
      - run: pip install mkdocs-material
      - run: mkdocs gh-deploy --force

9. Сохраните изменения, отправьте их на сервер;
10. Войдите в GitHub, создайте пул-реквест и слейте рабочую ветку с веткой main.
11. Перейдите в раздел Actions → All workflow. В списке workflow появилась новая запись — это и есть наш новый автоматический процесс. Если он завершился успешно (все этапы отмечены зелёными галочками), значит, всё получилось. Для проверки можете внести какие-нибудь изменения в исходные файлы и добавить их в ветку main. После сливания рабочей ветки с веткой main в Actions опять должен запуститься новый workflow. Дождитесь его завершения, перейдите на сайт и убедитесь, что там отобразились ваши изменения.

Получилось? Ура! А теперь давайте поймём, как именно это удалось.

GitHub Actions — это не просто вкладка в вашем репозитории. Это специальный сервис, который позволяет автоматизировать процессы сборки и деплоя вашего проекта. Workflow — это последовательность определенных действий, которые нужно совершить для того, чтобы ваш продукт был опубликован.
Workflow бывают разные. В прошлом уроке мы запускали workflow вручную с помощью специальной команды от MkDocs, а сегодня мы настроили workflow с автоматическим запуском. Как мы это сделали?
Мы создали папку github и подпапку workflows. Именно сюда GitHub Actions будет заходить, чтобы найти, не оставили ли вы ему каких-нибудь готовых workflow. Поэтому мы и положили сюда YAML-файл (gh-actions понимает именно этот формат файлов), внутри которого описали последовательность действий, необходимых для сборки и деплоя нашей доки. По сути, мы расписали работу команды mkdocs gh-deploy, только дополнительно указали, что workflow должен запускаться автоматически при обновлении ветки main:

<…>
on:
  push:
    branches:
      - main
<…>

Теперь после каждого обновления main GitHub Actions выполняет описанные нами в файле ci.yml действия и публикует новую версию сайта.

Конечно, здорово уметь самим писать файлы для workflow, но мы всё-таки на курсе для самых маленьких, поэтому я открою вам секрет: текст для ci.yml я не создал с нуля, а взял из официальной документации MkDocs-materials. Так что вы можете пройти по ссылке и проверить, всё ли правильно я скопировал)

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

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

P.S. Это ещё не всё, ведь я приготовил небольшой сюрприз. Тсс! Ставьте рукопожатия, и чуть позже я расскажу подробности 😎

#практика #docsascode

Привет!

Курс «Docs-as-code для самых маленьких» подошёл к концу, и я благодарен всем, кто принял в нём участие. Надеюсь, вы действительно узнали что-то новое и полезное для развития вашей карьеры.

Отдельная благодарность тем подписчикам, которые в курсе не участвовали, но терпеливо ждали его окончания, чтобы наконец увидеть посты на другие темы 🙃

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

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

Сертификат могут получить все желающие. Условие одно: ваш проект должен работать. Заполните форму, в которой укажи́те ссылки на репозиторий и опубликованный сайт, а также пройдите небольшой тест на проверку знаний. Результаты теста не влияют на получение сертификата, но с их помощью я попробую понять, насколько доступно и понятно объяснял вам материал.

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

Дисклеймер: сертификат только подтверждает ваше участие в большом мастер-классе по docs-as-code, не является документом об образовании и не имеет юридической силы.

#docsascode #практика

Docs as Code для самых маленьких

Практический мастер-класс по настройке инструментов для организации подхода docs-as-code.

1. Немного теории (читать здесь)
Что такое docs-as-code? Основные принципы подхода

2. Настройка окружения (читать здесь)
Установка необходимых программ

3. О командной строке (читать здесь)
Что такое командная строка и как ей пользоваться

4. Git-репозиторий (читать здесь)
Создание репозитория в GitHub

5. GIT (читать здесь)
Навыки работы с системой контроля версий

6. Клонирование репозитория (читать здесь)
Создание локальной копии репозитория

7. Создание первого файла (читать здесь)
Добавление первого документа в проект

8. Пул-реквест (часть 1 и часть 2)
Создание пул-реквеста и слияние веток

9. Кое-что о SSG (читать здесь)
Что такое генераторы статических сайтов

10. Установка SSG (читать здесь)
Установка и базовая настройка проекта MkDocs

11. Разработка структуры проекта (читать здесь)
Добавление исходных файлов и организация структуры проекта

12. Конфиг mkdocs.yml (читать здесь)
Настройка конфига проекта

13. Сборка и деплой проекта (часть 1 и часть 2)
Ручная и автоматическая сборка, публикация проекта на GitHub Pages

14. Финальный пост (читать здесь)
Как получить сертификат участника мастер-класса

#docsascode #практика

Привет!

Фух, это оказалось немного сложнее и дольше, чем я ожидал. Целый месяц тематических постов, который мы все мужественно выдержали!

Теперь мне кажется, что у меня атрофировалась способность писать про что-то кроме docs-as-code. Очень надеюсь, что это пройдёт в ближайшее время))

Нужно перебить сугубо профессиональные темы чем-то сугубо непрофессиональным. Например, мне вчера Озон опять прислал интригующее adult-уведомление: «Никто-никто не узнает. Но мы-то знаем, ага». То ли хотят денег взять за молчание, то ли ещё что. В любом случае я настроился на интересную подборку, а там оказались...
Маджонг и другие настольные игры. Спасибо, дорогой озон, что никому не расскажешь о моих извращённых увлечениях китайскими настолками. Очень признателен, но в следующий раз формулируй свои пуши чуть более прозрачно.

#флуд #ux

Ревью

Когда-то я работал в Яндексе координатором проекта. Ставил задачи другим техническим писателям, проверял их, оставлял замечания, снова проверял и отправлял в свободное плавание дальше по флоу.
Мне приходилось заниматься подобными делами и в других компаниях. И знаете, что я понял? Ревью чужих текстов — это работа едва ли не более сложная, чем написание доки.

Только представьте, вам приходит документ. Вам нужно проверить:
1. Факты;
2. Орфографию, пунктуацию, построение предложений;
3. Структуру (правильное выделение подразделов, глав, абзацев);
4. Оформление (стили в ворде, разметку в маркадун-файлах, etc.)

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

Стоит ли говорить, что также нужно иметь чёткое представление идеальной структуры и оформления именно этого конкретного документа?

Сделать процесс ревью легче и беззаботнее нам поможет стандартизация документации.

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

Правда, разработка шаблонов и стайлгайдов тоже занимает много времени и ресурсов. Но это того стоит, потом сами себе скажете «спасибо». Я говорил себе уже не раз :)

#практика

И снова про API

Обычно мне не везёт с розыгрышами. В конкурсах репостов я выиграл лишь однажды билет на концерт (который кому-то отдал, потому что не смог пойти).
Но недавно мне улыбнулась удача: в жёлтом чате технических писателей проходил конкурс-рандомайзер, и я оказался в числе победителей, получив в качестве приза промокод на любой курс от documentat.io. Это классные ребята, которые в числе прочего проводят курсы для технических писателей. Думаю, многие при старте карьеры смотрели их бесплатные уроки для новичков (к этим урокам и ведёт ссылка выше).

Если что, это не реклама документатио, думаю, они в ней не нуждаются.

В общем, я записался на курс по документированию API. Давно хотел разобраться с этим как следует и бесплатно. Курс стартует в конце ноября, и я обязательно поделюсь с вами впечатлениями после.

А есть ли бесплатные курсы по API? Ура, они есть, и даже несколько. Но несколько я предлагать не буду, а только один, который показался мне особенно интересным. Это курс по проектированию и документированию API от моего коллеги Дениса, который он проводит на своём канале. Тема очень интересная, а Денис настоящий апи-гуру, так что это однозначно рекомендасьён.

Я немного задержался (мы тут недавно пилили кучу контента по docs-as-code), но планирую начать выполнять задания от Дениса, потому что давно ждал, когда он начнёт делиться своим опытом и знаниями.

Приходите и вы, там интересно!

#api #практика

Хотел поговорить о чём-нибудь полезном, но пятница, вечер — какое тут рабочее настроение?
Поэтому лучше поговорим о высоком 🧐

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

Однажды я читал книгу, которую написал сценарист. И знаете что? У него не получилось. Точнее, так: это был сценарий фильма, который попытались замаскировать под литературу. Но очень подробные описания окружающей обстановки, а также внешности и действий героев выдали автора с потрохами.

Не превратит ли технический писатель интересную историю в сухое перечисление событий с уничтоженными или унифицированными эпитетами? Шанс высок.

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

В конце-концов, можно писать как Хэмингуэй: короткими чёткими предложениями без лишних сантиментов и украшений. Помню, как в юности я удивился, читая его «По ком звонит колокол» : на протяжении всего романа автор называл главного героя только по имени и фамилии и ни разу не использовал синонимы или хотя бы имя без фамилии или фамилию без имени. Но теперь-то я понимаю: он просто придерживался своего глоссария и не хотел нарушать консистентность терминов 🙃

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

P.S. Ставьте 👌, если пробовали себя в художественной литературе, посмотрим, сколько среди нас Эрнестов:)

#флуд

Иногда в быту мы путаем термины и называем вещи чужими именами. Например, громоотвод вместо молниеотвода, вес вместо массы, курок вместо спускового крючка, подъезд вместо парадной
Всё это лексические заблуждения, которые плотно вошли в нашу повседневность.

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

Часто ли вам приходилось слышать или видеть просьбу авторизоваться в приложении или на сайте? Мы авторизовываемся почти каждый день, используя свои логин и пароль от учетной записи.
А если в аккаунте настроена двухфакторная аутентификация, то после ввода логина и пароля нам приходит смс с кодом или поступает входящий звонок, и уже по правильно введённой комбинации цифр окончательно получаем доступ к личному кабинету и функциям приложения/сайта/программы.

Вроде, всё просто. Но почему в первом случае использовали слово «авторизация», а во втором — уже «аутентификация»? В чём сходство и отличие этих понятий?

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

1. Аутентификация — это проверка личности пользователя перед предоставлением ему доступа в сервис. Самый распространённый метод аутентификации — использование уникальных учётных данных (пары логин / пароль). Пользователь вводит данные для входа, система сравнивает их с теми, что хранятся у неё и определяет, имеет ли право пользователь с такой комбинацией логина и пароля получить доступ к учётной записи.
Также личность можно подтвердить с помощью одноразового пароля или электронного ключа доступа. Двухфакторная аутентификация использует комбинацию двух разных способов подтверждения, трёхфакторная — всех трёх способов.

2. Авторизация — это определение уровня доступа пользователя к ресурсам сервиса. После того, как система подтвердила личность пользователя, она определяет, какие права ему предоставить, а какие — нет. Например, пользователь может просматривать все комментарии, но редактировать только те, которые написал он сам.
Ролевая модель — один из популярных методов управления доступами. Каждому пользователю сервиса назначается роль с уже определённым набором прав. Администратор телеграм-канала может писать и редактировать посты, управлять настройками и подписками, владелец канала может делать всё то же самое, а также управлять правами других администраторов, а простой подписчик ничем не управляет, но может читать публикации, комментировать их и оставлять свои реакции (нет-нет, я ни на что не намекаю 🕊).

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

P.S. Этим постом я открываю новую рубрику #глоссарий, в рамках которой мы будем говорить о разных понятиях в айти. Пишите в комментариях, какие термины вы хотели бы разобрать в нашей новой рубрике, и мы обязательно за них возьмёмся! Когда-нибудь 🙃

#продолжи_мысль_SE

Привет!

Немного выпал из активного блогинга. Всё дело в работе — я с головой погрузился в рефакторинг внутренней доки. Дело это, хоть и кропотливое, но очень занимательное: всё-таки разработчики и другие хардовые спецы, вынужденно составляющие документацию, не связаны узами техписательских ограничений и могут себе позволить подойти к задаче творчески. Например, одна из инструкций начиналась так:

Набросал для самых маленьких. Стиль рассказа странный, но настроение было именно такое <...>

Это же просто песня! Я так и вижу, как человек заваривает себе чай покрепче, устраивается поудобнее в кресле, тяжело вздыхает и начинает набивать этот текст.

Или вот, стандартная step-by-step инструкция (пошаговая вообще-то, но step-by-step выглядит круче), как вдруг, в одном из пунктов ближе к концу встречается такой пассаж:

17. После прохождения всех этих кругов ада вы сможете нажать такую-то кнопку <...>

И сразу чувствуется эмпатия, видно, что автор понимает, как нам сложно, и даже немного нам сочувствует.

А этот текст, выразивший всю боль и отчаяние другого автора, оказался очень лаконичным:

to be...

Я всё это читаю с большим удовольствием, а потом тихонько правлю, переделывая прекрасные песни в сухие инфостильные тексты. Такая работа, что поделать.

#практика #флуд

Как рождается документация?

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

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

Но в этот раз что-то пошло не так:) В этот раз я попробовал новый метод разработки документации, от противного.

Создал новый файл. Чистый лист: пиши, что хочешь! Собственно, этим я занялся. Стал в один документ записывать всё-всё, что должно быть в разделе. Про настройки и про конфиги, про деплой и про оформление блоков кода, и даже немного про пунктуацию.

Получилось занимательно: смешались кони, люди, пользовательские инструкции и пространные описания, структурные схемы и примеры синтаксиса маркдауна. На какие-то темы не хватало сил, и я их отмечал просто пустыми заголовками, чтобы не забыть. В общем, вышла наваристая солянка из самой разношёрстной информации.

И теперь, когда контент готов, я с удовольствием разбираю его на абзацы и подразделы. Очень напоминает пасьянс «Паук» из далекого прошлого на Windows XP: кропотливая и увлекательная работа по раскладыванию карт по старшинству и масти данных по темам и отдельным статьям. Прямо на глазах из хаоса постепенно возникает красивая структурированная документация.

Метод проверен, налетай, кому не страшно:) Сначала создаем огромный черновик с кучей мусора, а потом с помощью усидчивости и упорного труда делаем из него конфетку, сразу несколько штук 🍬🍬🍬

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

#практика