Казалось бы, с документацией всё просто — пишешь, публикуешь, поддерживаешь актуальность. Например, вот у нас в Ozon есть пользовательские инструкции на docs.ozon.ru: выглядит просто как текст на сайтике, что ж необычного-то в его размещении и в целом в работе техписателей? 

Если начать раскапывать, всплывёт ещё несколько вопросов:

• где хранить тексты и почему Confluence не подходит?

• как красиво оформить документацию с помощью статических генераторов сайтов

• зачем техписателям знать git и CI/CD?

• в какой момент пора искать разработчиков в команду и превращать документацию в платформу?

На связи Катя — руководитель отдела технических писателей в Ozon, и сегодня расскажу о платформе Docs Ozon изнутри.

Подробно с демонстрацией своего кода рассказываю о том, как я реализовал в своем приложении на Kotlin добавление, редактирование, удаление и чтение событий из Google календаря при помощи Content Provider. Описываю "грабли", на которые наступал, не найдя в сети помощи и поддержки в тяжелое для себя время...

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

Не рассматриваются подходы с использованием Markdown, Pandoc, Asciidoc и Confluence как более сложные и узкоспециализированные, а статью хотелось сделать доступной и понятной не только молодым людям, но и людям старших возрастов.

В данной статье мы расскажем как перевести статический веб-сайт с Markdown (Zola, Hugo, Jekyll, Pelican, Gatsby, и д.р.) на все языки мира и поддерживать переводы в актуальном состоянии при изменении исходных текстов.

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

Лично мне завесу тайны приоткрыл Альфа-Банк, здесь документация ведется рядом с кодом, и схемы логичнее описывать тоже кодом. Но это не так страшно и не так сложно (почти) как кажется. Давайте я приоткрою ящик Пандоры и сниму кармическое проклятье с  этого инструмента. 

«Лучший способ в чём-то разобраться до конца — это попробовать научить этому компьютер». Дональд Кнут (как минимум викицитатник говорит, что он так сказал).

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

Для тех, кто, как и я, испытывал похожие проблемы, я решил поделиться своим методом.

Я работаю продакт-менеджером двух команд в Wrike на удалёнке и каждую неделю провожу примерно 20 часов на созвонах. В таких условиях контекст часто теряется из-за отсутствия физического контакта, а если ещё и камера так себе, то вместо лица человека видишь «кашу» без эмоций. Особенно обидно видеть тренинги или выступления именитых спикеров со стандартной камерой в тёмной комнате на фоне обоев, в то время как стоимость подобных тренингов  в разы превышает стоимость нормального оборудования. 

Я решил использовать свой опыт фотографирования и работы со светом и потратить время, чтобы улучшить свои Zoom-звонки «по-быстрому». И теперь хочу научить этому вас! В этой статье попробуем разобраться, какие технические средства можно использовать, чтобы онлайн-встреча напоминала встречу вживую и радовала и вас, и собеседника.

Docs as Сode — подход к работе с текстами, подразумевающий написание текста как кода:

• в простом текстовом редакторе или IDE;
• с использованием системы контроля версий;
• с CI / CD / Code Review.

В настоящее время Docs as Code широко применяется при работе с технической документацией, давая техническим писателям и проектным командам массу удобств и преимуществ.

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

В этой статье я расскажу о таком эксперименте (забегая вперед, удачном). Моей дочери 11 лет, она пишет сказки, стихи и рассказы. Чтобы поддержать ее увлечение, я помог ей создать литературный сайт, используя подход Docs as Code. Она успешно освоила основы Markdown и Git. Сейчас она самостоятельно публикует новые произведения и обновляет новости на своем сайте https://lib-beliakova.github.io/.

Привет, Хабр! Меня зовут Татьяна Шуравина, я системный аналитик Innovative People, работаю на проекте в банковском секторе. Вместе с командой оптимизируем и автоматизируем операции сотрудников банка для обслуживания юридических лиц. В своей первой статье я рассказывала, как стать системным аналитиком без специального образования. Сегодня хочу поделиться с теми, кто начал свой путь в аналитике, тонкостями магического процесса ведения проектной документации. Не для кого не секрет, что зачастую бывает такое, что система есть, а документации, чтобы понять, как она работает, нет. В статье расскажу, какие есть подходы к ведению документации, зачем это нужно и поделюсь практическим опытом.

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

Еще есть ГОСТы 34 и 19 — там уже написано, из каких разделов должен состоять стандартизованный документ, но ведь кроме стандартизованных есть и другие документы — во всяком случае заказы на таковые ко мне приходили, — и каждый раз приходилось ломать голову.

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

Привет! Это Теодора — технический писатель Платформы, жизненно важного департамента Ozon. Документация для нас имеет большое значение, потому что вся компания пользуется нашими разработками: инфраструктурой as a service; фреймворками и библиотеками; инструментами для работы с базами данных и аналитикой и прочим. Сотни инженеров ежедневно обращаются к нашим сервисам и нуждаются в их описании.

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

Анна Вичугова, CBAP, написала стартовое пособие по тому, как начать моделировать бизнес-процессы в BPMN

1. Назначение BPMN.

2. Уровни моделирования.

3. Алфавит нотации: События, Логические операторы, Артефакты.

4. Правила построения диаграмм.

5. Пример построения диаграммы по тексту.

6. Рекомендуемые инструменты.

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

А сегодня мы с вами быстро и решительно легко и просто поднимем свое личное файловое облако типа Google Drive или Яндекс.Диск, а если повезет, то еще и очень дешево.

Зачем? Ну, например, потому что не хотим зависеть от корпораций с их кабальными лицензионными соглашениями и сменой условий задним числом. Или потому что нам хочется приватности. Или просто потому что можем. А бонусом на нашем сервере вы потом сможете еще установить VPN или прокси для доступа к запрещенным сайтам, или поднять простенький веб-сайтик.

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

Люди уходят в IT отовсюду: из инженеров КИПиА, электротехников, начальников службы охраны, химиков, бухгалтеров, экономистов, металлургов, юристов, медбратьев, руководителей отдела рекламы. Люди уходят в IT в любом возрасте: в 20, 30, 40 лет и даже после 50. 

Зачем? Почему? Что им на месте не сидится? Почему все «прутся» в это IT? Есть несколько факторов, которые этому поспособствовали. Некоторые из них мы рассмотрим. Они на самые глобальные, но важные.