Данная статья не предполагает каких-то заумных и крайне неочевидных советов по написанию и проверке технической документации. Многие из перечисленных «советов» многим покажутся очевидными, но из раза в раз, анализируя документацию наших пользователей, мы сталкиваемся с одними и теми же банальными ошибками, которые чаще всего происходят из-за фактора «забыл». Так что данный пост можно расценить как памятку не техническому писателю.
Приятного чтения.
«Мои письма никто не читает.»
«Я уже всё всем написал, а коллеги продолжают спрашивать одно и то же. Бесит.»
И особенно популярное: «Мы ещё неделю назад написали, что удалим эту таблицу из базы, и сказали адаптировать код! Так что мы не виноваты, что сайт (пайплайн, приложение, <подставь своё>) упали.»
Начну с весьма непопулярного заявления: ответственность за доставку и восприятие сообщения процентов на семьдесят лежит на отправителе (то есть на тебе). Конечно, если твой коллега — заядлый социопат и в принципе не читает никакиеЧитать полностью »
Что может быть проще! Берёшь бумагу и ручку, или пишущую машинку, или что там у вас нынче в моде, и пишешь статью.
Как бы то ни было, для большого количества людей это всё равно считается заоблачным. Некоторые говорили, что для того, чтобы писать, нужен дар божий, а некоторые сидят и ждут, когда прилетит муза и начнёт играть на арфе.
Всё это фигня. Нам, айтишникам, нужны реальные инструкции о том, как что-то сделать. Давайте я вам расскажу о том как научится писать. Причём писать круто и интересно. Ведь профессия эта — древняя и хорошо всем знакомая. Не может же быть так, что вообще никто ничего не знает о том, как писать.
На самом деле знают, но почему-то превращают это знание в кучу эзотерических фактов о жизни фей в райских садах. Почему? Не знаю. Возможно потому, что сами такие люди ничего не знают о том, как что-то написать. А ведь это — достаточно просто. Посему, прошу под кат, я вам дам реальные советы по поводу того, как научиться хорошо писать интересные статьи. Читать полностью »
— Ну, там можно научиться огромному количеству новых и неизвестных вещей.
— А… Правда? Ок, удиви меня.
— Вот! – наивный юнец с радостью ткнул на указатель на приборной панели своей «Хонды».
— И что же в этом такого прикольного?
— Видишь стрелку? Она показывает с какой стороны у тебя крышка бензобака, чтобы ты помнил, где останавливаться у бензоколонки.
Я тяжело вздохнул, открыл бардачок, и, к ужасу парнишки, извлёк из него потрёпанный мануал 2004 года выпуска. После 20 секунд листания оного мануала, я ткнул пальцем в ту самую иконку, которая показывает, с какой стороны у тебя бензобак.
— Ну вот, пожалуйста. Это было известно ещё до «Тик-тока», и даже до «Фэйсбука». Эх! Это было известно ещё до интернета и, возможно, до появления автоматической коробки передач. Это было известно до того, как твои родители появились на свет. Ты мануал-то читал?
— Нет.
— Оно и видно.
Признайтесь, люди не читают мануалов. Давайте посмотрим, что Вам можно посоветовать, чтобы люди от них вообще избавились.
Читать полностью »
JSDoc - это язык разметки, используемый для аннотирования исходного кода JavaScript с использованием комментариев. Аннотации обрабатывается различными инструментами для создания документации в доступных форматах, таких как HTML и Rich Text Format.
Для создания проекта выполните следующие команды:
mkdir learn-jsdoc && cd learn-jsdoc - создание каталога проекта.
npm init -y - инициализация проекта.
touch index.js - создание файла index.js
Выполните установку JSDoc одним из следующих способов:
Глобально: sudo npm install -g jsdoc
Богатый язык инженера - это ещё один способ утвердить свой профессиональный уровень в глазах окружающих.
- Ооо, ты инженер конструктор?
- Да!
- Скажи что-нибудь как инженер конструктор!
-Крыльчатка насоса.
- Бог с ним, отправляй, по замечаниям исправим...
Если я всё правильно понимаю, в феврале 2021 года Atlasian прекратил продажу серверной версии Confluence.
On February 2, 2021 Pacific Time (PT), the following changes will go into effect:
- End of new server license sales: You can no longer purchase or request a quote for a new server product.
- Updates to server prices: We will implement new prices for server renewals and upgrades.
Продолжаем рассказывать о применении на практике принципа работы с документацией как с кодом. В этот раз разберём получение спецификации Swagger напрямую из комментариев к коду API. В статье рассматривается роль технического писателя в процессе адаптации команды к использованию нового инструмента, а также приводятся конкретные инструкции по применению swagger-php в реальном проекте.
Читать полностью »
Процесс документирования архитектуры программного обеспечения может показаться пугающим. Но на самом деле достаточно всего 5 диаграмм, чтобы объяснить структуру вашей системы практически любому.
