Size: a a a

Technical Writing 101

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

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

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

🔗 Читать: Should you use the first-person plural in your documentation?
источник
2021 June 23
Technical Writing 101
💡Мечтать не вредно, но и вредно не мечтать, или сказ об идеальных митингах.

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

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

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

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

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

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

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

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

🔗 Читать: The Document Culture of Amazon
источник
2021 June 29
Technical Writing 101
Notion запустил Synced Blocks!

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

P.S

Ссылочка, собсно, на блогпост с историей формата, небольшим экскурсом в 60-е и ходом мысли по ходу разработки фичи
источник
Technical Writing 101
Люблю честные чейнджлоги ❤️
источник
2021 June 30
Technical Writing 101
💰 Подъехали результаты опроса по зарплатам Техписателей за 2020 год.

🔗 Читать: Write the Docs Salary Survey 2020 Results
источник
2021 July 14
Technical Writing 101
Kathy Korevec, Продукт Манагер из GitHub, написала занимательнейшую статью с просто горооой размышлений о том, как улучшить документацию в GitHub. Кроме того, она нагенерировала еще ведро идей о том, как оптимизировать документацию для разработчиков, и подкрепила их мокапами. Говорит о необходимости “многоформатности” документации, об оптимизации поиска, в общем очень интересный взгляд внутрь головы продукт манагера довольно таки большой компании, рекомендуется к прочтению.

🔗Читать: Maybe it’s time we re-think docs
источник
2021 July 29
Technical Writing 101
И мы плавно возвращаемся из отпуска! Stay tuned..накопилось много годноты.
источник
2021 August 02
Technical Writing 101
Да, иногда даже на Хабре бывает полезный и читабельный контент.

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

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

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

🔗 Читать: Как (не) нужно строить базу знаний для проекта с нуля. Часть Первая, утопическаяКак (не) нужно строить базу знаний для проекта с нуля. Часть Первая, утопическая
источник
2021 August 04
Technical Writing 101
🔥 Небольшой мотивационный пост, приуроченный к красивому числу подписчиков!

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

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

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

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

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

🔗 Читать: The uber-importance of docs
источник
2021 August 16
Technical Writing 101
При сравнении продуктов, вы хотите понять, какой все же из них лучше? Тем не менее мы часто забываем оценить документацию по проекту. Проект может предлагать отличный набор функций, но в то же время у него может не быть простой в использовании документации. Это может отрицательно сказаться на процессе использования продукта и эффективности вашей команды. Автор статьи предлагает, пусть и без откровений, научиться оценивать UX документации (со стороны разработчиков).

🔗 Читать: Developer Experience: How to Define Good Documentation?
источник
2021 August 20
Technical Writing 101
Немного апдейтов из мира стайлгайдов:

1. Google обновил часть своего стайлгайда про заголовки.
2. GitHub добавили раздел с правилами по написанию гендерно-нейтральной документации в свои гайдлайны.
источник
2021 August 30
Technical Writing 101
Джулия Эванс, регулярный гость в нашем уютном бложике, но на этот раз не с своими прекрасными Зинами Для Программистов, а с перечнем так-себе-паттернов затрудняющих восприятие информации и кайфовые примеры к ним.

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

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

🔗 Читать: Patterns in confusing explanations
источник
2021 September 01
Technical Writing 101
Давно мы что-то про тулзы не говорили (а ничего нового, кроме очередного 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), который еще и кастомными скриптами можно расширять, лепота. Все, что дополнение умеет, можно глянуть в доках.
источник
2021 September 02
Technical Writing 101
Продолжим марафон тулз.

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

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

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

Почитать больше можно в официальном блогпосте 🔗Use Markdown for Confluence и в соответствующем 🔗репозитории проекта.
источник
2021 September 15
Technical Writing 101
Тревожные (на самом деле не очень) вести с полей JAMStack. Автор поста «RIP Jekyll (The Genesis of the Jamstack)» переживает, что Джекилл отжил свое и пора двигаться дальше. Пост немного надуманный, отчасти истеричный, да и прямых доказательств и заявлений разработчиков не особо-то и было.

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

🔗 Читать: RIP Jekyll (The Genesis of the Jamstack)
источник
2021 September 21
Technical Writing 101
Переслано от Нац Нац
Немного о построении культуры документации на примере трёх IT-гигантов: Google, Twitter, Spotify.

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

🔗 Читать: How Google, Twitter, and Spotify built a culture of documentation
источник
2021 September 29
Technical Writing 101
Ситуация: вас наняли техническим писателем в недавно основанную или недавно очнувшуюся и требующую доки компанию. В ней нет ни-че-го (из документации), а должно быть очень многое. За что браться, куда бежать и как определить, что должно быть в Minimum Viable Documentation?

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

🔗 Читать: From Nothing to Something with Minimum Viable Documentation
источник
2021 October 05
Technical Writing 101
GitHub’овский Маркдаун научился в сноски
источник
2021 October 08
Technical Writing 101
Похоже у нас с вами вот-вот появится своя IDE (IWE?) от JetBrains!
источник
2021 October 14
Technical Writing 101
Переслано от Нац Нац
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
источник