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

Навернка во время написания технической документации, у вас возникала мысль использовать: “we”, “us”, и “ours”. Но в отличие от второго лица (“you”), использование “we” не так явно распространено или приемлемо.

Но не все так просто! Статья углубляется в вопрос использования “we” и кроме того, автор сравнивает как разные стайлгайды советуют поступать с вот этим вот всем.

🔗 Читать: Should you use the first-person plural in your documentation?

💡Мечтать не вредно, но и вредно не мечтать, или сказ об идеальных митингах.

Недавно я выкладывал пост про “Амазоновский Шестистраничник” (звучит как что-то из урбандикшнари, да), а теперь пришло время еще немного расширить границы познания о культуре документации в Amazon, ибо она крутая.

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

И в чем же секрет, спросите вы? Конечно же в чтении документации! Но ее и так читают, скажете вы? Как бы не так! Но тут речь идет о >document-based-митингах<, начинаются которые с (нет, вы только представьте) коллективного чтения документа.

В чем автор поста видит проблему обычных митингов:

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

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

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

И запомните, if there isn’t a doc there isn’t a meeting

🔗 Читать: The Document Culture of Amazon

Notion запустил Synced Blocks!

Вместо того, чтобы обновлять один и тот же кусок документа в миллионе мест, теперь можно создать Synced Block и ссылаться на него в любом другом месте, а изменения подтянутся :3

P.S

Ссылочка, собсно, на блогпост с историей формата, небольшим экскурсом в 60-е и ходом мысли по ходу разработки фичи

Люблю честные чейнджлоги ❤️

💰 Подъехали результаты опроса по зарплатам Техписателей за 2020 год.

🔗 Читать: Write the Docs Salary Survey 2020 Results

Kathy Korevec, Продукт Манагер из GitHub, написала занимательнейшую статью с просто горооой размышлений о том, как улучшить документацию в GitHub. Кроме того, она нагенерировала еще ведро идей о том, как оптимизировать документацию для разработчиков, и подкрепила их мокапами. Говорит о необходимости “многоформатности” документации, об оптимизации поиска, в общем очень интересный взгляд внутрь головы продукт манагера довольно таки большой компании, рекомендуется к прочтению.

🔗Читать: Maybe it’s time we re-think docs

И мы плавно возвращаемся из отпуска! Stay tuned..накопилось много годноты.

Да, иногда даже на Хабре бывает полезный и читабельный контент.

Kiii~nda саксесс стори с (пере)построением базы знаний, которая действительно работает и выполняет свои задачи, а еще все это дело в Notion.

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

Ждем продолжение, ну а пока, всем хорошего старта рабочей недели 🙏

🔗 Читать: Как (не) нужно строить базу знаний для проекта с нуля. Часть Первая, утопическаяКак (не) нужно строить базу знаний для проекта с нуля. Часть Первая, утопическая

🔥 Небольшой мотивационный пост, приуроченный к красивому числу подписчиков!

Спасибо, что вы есть 😘

Мы тут не постоянно, но регулярно напоминаем себе, как важны техписы, и что нас всех стоит ценить.

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

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

И помните, it doesn’t matter how great your software is if nobody understands how or why they should use it 👆

🔗 Читать: The uber-importance of docs

При сравнении продуктов, вы хотите понять, какой все же из них лучше? Тем не менее мы часто забываем оценить документацию по проекту. Проект может предлагать отличный набор функций, но в то же время у него может не быть простой в использовании документации. Это может отрицательно сказаться на процессе использования продукта и эффективности вашей команды. Автор статьи предлагает, пусть и без откровений, научиться оценивать UX документации (со стороны разработчиков).

🔗 Читать: Developer Experience: How to Define Good Documentation?

Немного апдейтов из мира стайлгайдов:

1. Google обновил часть своего стайлгайда про заголовки.
2. GitHub добавили раздел с правилами по написанию гендерно-нейтральной документации в свои гайдлайны.

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

💥паттерн 1: делать устаревшие предположения об знаниях аудитории
💥паттерн 2: наличие противоречивых ожиданий относительно знаний читателя
💥паттерн 3: натянутые аналогии
💥паттерн 4: забавные иллюстрации на сухих объяснениях
💥паттерн 5: нереалистичные примеры
💥паттерн 6: жаргон, который ничего не значит
💥паттерн 7: отсутствует ключевая информация
💥паттерн 8: вводится слишком много концепций одновременно
💥паттерн 9: начинаете абстрактно
💥паттерн 10: неподдерживаемые ничем утверждения
💥паттерн 11: нет примеров
💥паттерн 12: объяснять «неправильный» способ сделать что-то, не говоря, что это неправильно
💥паттерн 13: «что» без «почему»

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

🔗 Читать: Patterns in confusing explanations

Давно мы что-то про тулзы не говорили (а ничего нового, кроме очередного yet another best-on-the-market markdown editor не выдумали). Но мы то знаем, какой редактор нужен техписателю, и нет, это не Microsoft Word, это, конечно же, VS Code.

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

Front Matter — это такая себе локальная headless CMS для менеджмента ваших статических сайтиков (цитата: Hugo, Jekyll, Hexo, NextJs, Gatsby, and many more), который еще и кастомными скриптами можно расширять, лепота. Все, что дополнение умеет, можно глянуть в доках.

Продолжим марафон тулз.

Часто наблюдаю, как невольные пользователи Confluence хотят причаститься к чему-то посовременнее, и, например, линтить текст в VS Code и писать в Markdown. Но как все это дело потом впихнуть в Конфу? Копипаст это скучно и к тому же утомительно.

А хочется чего-то большего, хочется git blame, хочется не кривую и скудную нативную историю изменений Confluence, а простых человеческих пуллреквестов. А может у вас даже появлялись мысли о Continuous Integration? Fear not, теперь все это можно, некий Egor Kovetskiy уже довольно давно девелопит и регулярно обновляет прекрасную тулзу под названием Mark.

Марк позволяет делать все вышеперечисленное, для этого вам просто нужно слегка сбрызнуть ваши .md файлы html-лайк метадата хэдерами и запустить миниатюрный бинарник на Go (отдельный респект).

Почитать больше можно в официальном блогпосте 🔗Use Markdown for Confluence и в соответствующем 🔗репозитории проекта.

Тревожные (на самом деле не очень) вести с полей JAMStack. Автор поста «RIP Jekyll (The Genesis of the Jamstack)» переживает, что Джекилл отжил свое и пора двигаться дальше. Пост немного надуманный, отчасти истеричный, да и прямых доказательств и заявлений разработчиков не особо-то и было.

Мой пойнт скорее в том, что хорошо бы научиться орудовать несколькими утилитами/языками/фреймворками/подходами, которые более-менее актуальны в вашей сфере сегодня. Остаться за бортом технологического прогресса довольно легко, и в нашей с вами области это отлично видно по количеству пользователей всяких DITA, MadCap Flare, Word и иже с ними.

🔗 Читать: RIP Jekyll (The Genesis of the Jamstack)

Немного о построении культуры документации на примере трёх IT-гигантов: Google, Twitter, Spotify.

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

🔗 Читать: How Google, Twitter, and Spotify built a culture of documentation

Ситуация: вас наняли техническим писателем в недавно основанную или недавно очнувшуюся и требующую доки компанию. В ней нет ни-че-го (из документации), а должно быть очень многое. За что браться, куда бежать и как определить, что должно быть в Minimum Viable Documentation?

Очень информативный лонгрид под слоганом «Get from nothing to something with MVD» поможет не запаниковать и ответить на все вопросы выше.

🔗 Читать: From Nothing to Something with Minimum Viable Documentation

GitHub’овский Маркдаун научился в сноски

Похоже у нас с вами вот-вот появится своя IDE (IWE?) от JetBrains!

Write the Docs проводит третий ежегодный зарплатный опрос.

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

Вот, что говорят о целях и пользе авторы опроса:

«We hope this data helps our community members determine what appropriate salary ranges are, and provide a benchmark for future employment-related decisions and negotiations.

Additionally, we’re hoping the results spark discussion of employment-related trends and issues in our industry, including but not limited to the effects of the COVID-19 pandemic.»

🔗 Заполнить Documentation Salary Survey 2021