Как стать автором
Обновить
53.83

Подготовка технической документации *

Всё о деятельности технических писателей

Сначала показывать
Порог рейтинга
Уровень сложности

«ПЯТНО НА ВАЗЕ» – мнемоника для тестирования требований

Уровень сложностиПростой
Время на прочтение4 мин
Количество просмотров261

Привет, Хабр! Я являюсь тестировщиком компании TravelLine. Мы разрабатываем единую систему для гостиничного предприятия, которая помогает отелям, санаториям и другим средствам размещения автоматизировать бизнес-процессы.

В тестировании своих продуктов мы придерживаемся подхода «Shift Left» или «Сдвиг влево». Суть этого подхода — смещение фазы тестирования влево в жизненном цикле продукта и проведение тестирования на каждом этапе разработки. Одной из техник, которая помогает смещать тестирование влево является тестирование документации и требований.

Читать далее
Рейтинг0
Комментарии0

Новости

Очередной обзор очередного курса. Или как техпис на системного аналитика в «Нетологии» учился

Время на прочтение5 мин
Количество просмотров925

Привет, Хабр.

Знаю, что здесь куча обзоров на различные курсы от разных школ, платформ и иже с ними. Но все-таки хочу вставить и свои 5 копеек. Рассказываю о своих ощущениях от курса «Системный аналитик», который я (успешно) окончил в августе 2024 года.

Почему я вообще в это все ввязался?

Ну давай, расскажи
Всего голосов 4: ↑0 и ↓4-4
Комментарии2

Markdown Editor: WYSIWYG и markup-редактор на базе Gravity UI

Уровень сложностиПростой
Время на прочтение7 мин
Количество просмотров5.6K

Привет, Хабр! Меня зовут Сергей Махнаткин, я работаю разработчиком в отделе User Experience в Yandex Cloud. В прошлом году мы писали о нашей дизайн-системе и библиотеке компонентов Gravity UI. С тех пор система не раз обновлялась и обрастала новыми функциями, и сегодня я хочу рассказать о новом инструменте — Markdown Editor, который значительно упрощает процесс работы с документацией.

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

Читать далее
Всего голосов 37: ↑36 и ↓1+54
Комментарии17

Немного о подходе Architecture Decision Records

Уровень сложностиПростой
Время на прочтение7 мин
Количество просмотров1.5K

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

При этом, мы не всегда можем четко определить, какие из принятых нами решений в процессе работы являются архитектурными, то есть требующими обязательного документирования, а какие таковыми не являются, хотя также очень важны для проекта. Когда архитектура программного обеспечения развивается в результате принятия командой ряда решений, командам разработчиков требуется способ отслеживать принятые ими архитектурные решения. И здесь им на помощь приходит отчет об архитектурных решениях Architecture Decision Records (ADR). По сути, ADR — это документы, которые описывают принятые архитектурные решения в проекте или системе. Они используются для сохранения и передачи информации о принятых решениях и обосновании их принятия.

Читать далее
Всего голосов 9: ↑9 и ↓0+13
Комментарии0

Истории

Надежность в процессах. Часть 2

Уровень сложностиСредний
Время на прочтение12 мин
Количество просмотров884

1 Терминология

В «Надежность в процессах. Часть 1» [OpRes24-1] были определены (упрощены): надежность, процесс и надежность в процессах. Надежность – это способность безотказно работать (работать без отказов). Надежность процесса – это как способность безотказно работать («главное процесс»), так и выдавать требуемый результат («главное результат»). Количественно – это вероятность безотказной работы (вероятность застать процесс работоспособным) и вероятность требуемого результата на выходе процесса.

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

Это относится как ИТ-системе (кластер серверов) и не ИТ-системе (сейф), так и к системе процессов (операций) и составных частей процесса, включая его ресурсы.

Если в классической теории надёжности (Надёжность в технике [27.002]) обычно рассматриваются внутренние воздействующие деструктивные факторы на техническую систему типа отказ \ сбой оборудования \ ПО, то «Надежность в процессах и операциях» (операционная надёжность) рассматривает также непреднамеренные ошибки персонала (операционные риски) и внутреннее мошенничество, внешние атаки на процессы компании, клиентов компании (социальная инженерия), стихийные бедствия (техногенные катастрофы). В конечном счете неважно: «система процессов» отказала (не выполнила задачу) из-за какой-либо поломки или из-за ее перегрузки (от нежданного «наплыва клиентов» до DDoS-атаки), поэтому в состав показателей Надежность в процессах добавляем «доступность»:

Читать далее
Всего голосов 5: ↑4 и ↓1+6
Комментарии0

Создаем свою простую (C++) библиотеку с документацией, CMake и блекджеком

Уровень сложностиСредний
Время на прочтение33 мин
Количество просмотров11K

В мире программирования создание собственных библиотек — это не просто возможность пополнения своего портфолио или способ структурировать код, а настоящий акт творческого самовыражения (и иногда велосипедостроения). Каждый разработчик иногда использовал в нескольких своих проектах однообразный код, который приходилось каждый раз перемещать. Да и хотя бы как упаковать свои идеи и знания в удобный и доступный формат, которым можно будет поделиться с сообществом.

Если вы ловили себя на мысли: ‭«А почему мне бы не создать свою полноценную библиотеку?‭», то я рекомендую прочитать вам мою статью.

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

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

Читать далее
Всего голосов 44: ↑43 и ↓1+53
Комментарии59

Как построить управление корпоративными знаниями по ИТ-продукту

Уровень сложностиСредний
Время на прочтение7 мин
Количество просмотров1.9K

Хочу поделиться своим опытом организации и построения корпоративной базы знаний для продуктовой ИТ-разработки. В конце статьи подведу итоги внедрения такой системы.

Читать далее
Всего голосов 5: ↑4 и ↓1+7
Комментарии2

Надежность в процессах. Часть 1

Уровень сложностиСредний
Время на прочтение20 мин
Количество просмотров1.8K

Прежде, чем объединяться, нам надо решительно размежеваться (Business continuity management vs Business Process Continuity vs Dependability in technics)

Синонимы: Надежность в процессах = надежность процессов = надежность операций = операционная надежность (с учетом синонимии словосочетаниями «сущ. + сущ.» [Морф23]).

En: dependability, reliability, resilience (availability, stability) Business Process. Непрерывность процессов — в контексте «business continuity» (Business Process Continuity, BPC) и т. п.

Читать далее
Всего голосов 5: ↑4 и ↓1+7
Комментарии9

Основные проблемы автоматизации процессов лаборатории

Уровень сложностиПростой
Время на прочтение10 мин
Количество просмотров1.3K

Хотелось бы немного осветить тему про ЛИМС на Хабре. В мире существует огромное множество лабораторий, которые занимаются измерениями, испытаниями, анализом каких-то объектов окружающей среды, продукции, биологических образцов и т.д.

Поговорим про внедрение ЛИМС в лаборатории.

Читать далее
Всего голосов 6: ↑5 и ↓1+10
Комментарии0

Как собрать и запустить отдел по работе с инцидентами в продакшене — разбираемся в статье-инструкции

Уровень сложностиПростой
Время на прочтение4 мин
Количество просмотров678

Привет, Хабр! Я — Алексей Ткаченко, руководитель отдела L1 в диджитал-продакшене Далее. Наша команда отвечает за мониторинг работоспособности ресурсов клиентов, оперативно реагирует на проблемы и помогает с ними разбираться. Попутно облегчает жизнь клиентов и менеджеров. Расскажу, зачем бизнесу может понадобиться такой отдел, как строится работа в команде и к каким результатам мы пришли за год. 

Читать далее
Всего голосов 7: ↑4 и ↓3+5
Комментарии1

Как я при помощи двух «костылей» смог автоматически сгенерировать опись документов для 700 страниц

Уровень сложностиСредний
Время на прочтение4 мин
Количество просмотров6.4K

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

Ситуацию несколько облегчает то, что на эти распечатанные документы есть исходные Excel файлы.

Автоматизируем создание описи документов🤖
Всего голосов 8: ↑8 и ↓0+12
Комментарии7

Автоматическая сборка examples для Swagger NestJs

Уровень сложностиПростой
Время на прочтение4 мин
Количество просмотров1K

Кейс о том как автоматизировать сбор данных и формирования examples с типами в Swagger без описании сущностей, с использованием фреймворка NestJs.

Читать далее
Всего голосов 4: ↑2 и ↓2+2
Комментарии0

Почему котику лучше в коробке, или Как мы сокращаем этап ревью и согласования документации

Уровень сложностиПростой
Время на прочтение7 мин
Количество просмотров3K

Привет! Меня зовут Елена Павлова, и более 10 лет я работаю в сфере IT. В этой статье расскажу, что помогает мне и моей команде создавать документацию, которую легко читать и понимать.

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

Составляем требования грамотно →
Всего голосов 13: ↑12 и ↓1+13
Комментарии4

Ближайшие события

27 августа – 7 октября
Премия digital-кейсов «Проксима»
МоскваОнлайн
28 сентября – 5 октября
О! Хакатон
Онлайн
3 – 18 октября
Kokoc Hackathon 2024
Онлайн
10 – 11 октября
HR IT & Team Lead конференция «Битва за IT-таланты»
МоскваОнлайн
25 октября
Конференция по росту продуктов EGC’24
МоскваОнлайн
7 – 8 ноября
Конференция byteoilgas_conf 2024
МоскваОнлайн

Потенциал точек зрения ArchiMate: От обычного EA-моделирования до PLM

Уровень сложностиСредний
Время на прочтение16 мин
Количество просмотров1.2K

На протяжении всего моего времени работы с моделью и языком ArchiMate от The Open Group, внимательно наблюдая за практиками сообщества, я не переставал удивляться тому, насколько мало используются “точки зрения” (viewpoint’ы), предложенные в ArchiMate 2.1.

Я открыл их для себя благодаря отличному бесплатному опенсорсному решению Archi, разработанному Филлипом Бовуаром (Phillip Beauvoir), которое очень грамотно раскрывает потенциал представлений (view) в помощи заинтересованным сторонам, желающими создать всеобъемлющую модель архитектуры рассматриваемых ими организаций.

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

Я считаю, что понимать и уметь применять точки зрения так же важно, как и разбираться во всех остальных 60 (или около того) конструкциях языка ArchiMate.

Читать далее
Всего голосов 5: ↑5 и ↓0+9
Комментарии1

Документации быть

Уровень сложностиПростой
Время на прочтение7 мин
Количество просмотров6.5K

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

Читать далее
Всего голосов 13: ↑10 и ↓3+9
Комментарии26

Курица не птица, техпис не инженер

Время на прочтение10 мин
Количество просмотров3.3K

Привет, Хабр! Меня зовут Вячеслав Смирнов, я руковожу техническими писателями в Platform V Pangolin. Три года назад я пришел в продукт в качестве DBA, а спустя год организовал команду техписов и стал разрабатывать документацию.

Давным-давно команда Pangolin состояла из 15-20 человек. Документация по продукту была в зачаточном состоянии. Разработчики сами пилили фичи и сами же их описывали. Но потом Pangolin вырос, вышел на внешний рынок и нам стали нужны профессиональные технические писатели.

А мир техписов разнообразен: здесь есть и редакторы-корректоры, и технари, умеющие развернуть дистрибутив. Техписы без технического опыта не всегда готовы разбираться в сложном продукте. Но, как выяснилось на практике, и технарям, пришедшим в команду, не хватало погружения в тему СУБД, чтобы писать документацию. Попробовав разные варианты, мы нашли для себя такой выход: наши техписы обязательно проходят базовые курсы DBA, и мы берем в команду не только техписов, но и DBA, желающих писать доку.

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

Читать далее
Всего голосов 16: ↑14 и ↓2+18
Комментарии16

Собеседование по System Design: как запроектировать и не потеряться

Уровень сложностиСредний
Время на прочтение8 мин
Количество просмотров14K

Привет! Меня зовут Дмитрий. Я архитектор решений в крупной российской компании, более 15 лет проектирую, пишу код и руковожу командами. Сотрудничаю с Практикумом как ревьюер курса по Java и как автор курса «Архитектура программного обеспечения» в Яндекс Практикуме.

Предположим, вы решили развлечься дизайном систем (System design), пусть даже и не добровольно, на собеседовании. Если компания поленилась поделиться рабочим контекстом, то задача может быть в формате «запроектируй Твиттер». Более кандидатоориентированная компания N может попросить «спроектируй поиск на сервисе N».

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

Читать далее
Всего голосов 17: ↑15 и ↓2+16
Комментарии21

Кто такой технический писатель и как им стать

Уровень сложностиПростой
Время на прочтение10 мин
Количество просмотров2.7K

Привет, меня зовут Ольга Громыко. Я работаю техническим писателем в R‑Style Softlab и создаю документацию по банковскому ПО, которая помогает пользователям разобраться в работе сервисов. В статье подробно расскажу, чем занимается технический писатель, какие навыки помогают ему в работе и какие перспективы есть у таких специалистов.

Читать далее
Всего голосов 13: ↑12 и ↓1+18
Комментарии2

Роль технического писателя в IT компании. Внедрение тех. писателя в компанию

Уровень сложностиПростой
Время на прочтение5 мин
Количество просмотров1K

Всем привет! Меня зовут Илья, я технический писатель компании QTIM. Сегодня хотелось бы немного поговорить о своей профессии. 

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

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

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

Писатели могут заниматься написанием следующих типов документации:

Читать далее
Всего голосов 5: ↑3 и ↓2+3
Комментарии7

Прекратите делать таблицы в Markdown

Уровень сложностиПростой
Время на прочтение13 мин
Количество просмотров31K

В пятницу ко мне подошел коллега и с гордостью показал новую утилиту, которую он разработал. Она генерирует документацию в Markdown на основе .env файла, включая переменные, их значения и комментарии. Я, конечно, поздравил коллегу с успехом и попросил посмотреть на результат. И тут меня ждал шок — таблица в Markdown! Вы только представьте себе это!

Так начался холивар...

И что же не так с таблицами?
Всего голосов 66: ↑55 и ↓11+63
Комментарии79
1
23 ...