#документирование — Public Fediverse posts

Нужен ли синопсис технической документации? Личный опыт разработки

Разработка документации на создаваемые ИТ-продукты – это не только «правила хорошего тона», но и насущная необходимость. Ведь без технического задания невозможно зафиксировать требования к продукту, без руководства пользователя сложно грамотно продуктом пользоваться, без технической документации, описывающей продукт, сложно будет искать и исправлять ошибки и проводить необходимые доработки, когда в них возникнет необходимость, и т.д. Обычно документацию делают по одному из двух путей – либо используют стандарты, описывающие требования к составу, структуре и содержанию документов (например, ГОСТ 19-й и 34-й серий – ЕСПД и КСАС), либо самостоятельно разрабатывают документ, создавая его на основе собственного опыта или по существующим образцам, в т.ч. взятых из интернета. Но как же её правильно сделать? Мой ответ - начинать надо с синопсиса документов.

https://habr.com/ru/articles/1015118/

#Синопсис #документация #документирование #документация_проекта #разработка_документации #техническая_документация #технический_писатель #техническое_задание

Нужен ли синопсис технической документации? Личный опыт разработки

Разработка документации на создаваемые ИТ-продукты – это не только «правила хорошего тона», но и насущная необходимость. Ведь без технического задания невозможно зафиксировать требования к продукту, без руководства пользователя сложно грамотно продуктом пользоваться, без технической документации, описывающей продукт, сложно будет искать и исправлять ошибки и проводить необходимые доработки, когда в них возникнет необходимость, и т.д. Обычно документацию делают по одному из двух путей – либо используют стандарты, описывающие требования к составу, структуре и содержанию документов (например, ГОСТ 19-й и 34-й серий – ЕСПД и КСАС), либо самостоятельно разрабатывают документ, создавая его на основе собственного опыта или по существующим образцам, в т.ч. взятых из интернета. Но как же её правильно сделать? Мой ответ - начинать надо с синопсиса документов.

https://habr.com/ru/articles/1015118/

#Синопсис #документация #документирование #документация_проекта #разработка_документации #техническая_документация #технический_писатель #техническое_задание

Нужен ли синопсис технической документации? Личный опыт разработки

Разработка документации на создаваемые ИТ-продукты – это не только «правила хорошего тона», но и насущная необходимость. Ведь без технического задания невозможно зафиксировать требования к продукту, без руководства пользователя сложно грамотно продуктом пользоваться, без технической документации, описывающей продукт, сложно будет искать и исправлять ошибки и проводить необходимые доработки, когда в них возникнет необходимость, и т.д. Обычно документацию делают по одному из двух путей – либо используют стандарты, описывающие требования к составу, структуре и содержанию документов (например, ГОСТ 19-й и 34-й серий – ЕСПД и КСАС), либо самостоятельно разрабатывают документ, создавая его на основе собственного опыта или по существующим образцам, в т.ч. взятых из интернета. Но как же её правильно сделать? Мой ответ - начинать надо с синопсиса документов.

https://habr.com/ru/articles/1015118/

#Синопсис #документация #документирование #документация_проекта #разработка_документации #техническая_документация #технический_писатель #техническое_задание

Нужен ли синопсис технической документации? Личный опыт разработки

Разработка документации на создаваемые ИТ-продукты – это не только «правила хорошего тона», но и насущная необходимость. Ведь без технического задания невозможно зафиксировать требования к продукту, без руководства пользователя сложно грамотно продуктом пользоваться, без технической документации, описывающей продукт, сложно будет искать и исправлять ошибки и проводить необходимые доработки, когда в них возникнет необходимость, и т.д. Обычно документацию делают по одному из двух путей – либо используют стандарты, описывающие требования к составу, структуре и содержанию документов (например, ГОСТ 19-й и 34-й серий – ЕСПД и КСАС), либо самостоятельно разрабатывают документ, создавая его на основе собственного опыта или по существующим образцам, в т.ч. взятых из интернета. Но как же её правильно сделать? Мой ответ - начинать надо с синопсиса документов.

https://habr.com/ru/articles/1015118/

#Синопсис #документация #документирование #документация_проекта #разработка_документации #техническая_документация #технический_писатель #техническое_задание

Миллион за сисадмина: как один айтишник может остановить компанию на неделю

Эта статья для собственников и директоров малого и среднего бизнеса, у которых в компании есть один ИТ-специалист или ИТ-лидер, отвечающий за все разом. Если сейчас уход такого человека — это катастрофа, значит, бизнес уже живет с неоправданным риском. Причина здесь не в том, что айтишники плохие. Причина — в том, как выстроена система. Или не выстроена совсем. В этой статье разберем две реальные истории и покажем обе стороны медали: как собственник оказывается в зависимости, о которой сам не догадывается — и почему сам ИТ-специалист нередко становится заложником той же самой ситуации. И главное — как из неё выйти не через конфликт, а через процессы и правильно выстроенные отношения. Меня зовут Авдей Мартынович, больше 20 лет я занимаюсь поддержкой и развитием ИТ‑инфраструктуры для бизнеса. В этой статье разбираю, как один админ оказывается единственной точкой отказа, почему это проблема и для собственника, и для самого ИТ‑специалиста, а также какие процессы помогают снизить риски без войны и шантажа. Одна из последних наших историй — как раз про такую ситуацию: собственник решил сократить ИТ‑расходы и внезапно осознал, насколько сильно бизнес зависит от одного человека, у которого сосредоточены ключевые доступы и знание инфраструктуры. Подробности расскажу в первой истории ниже.

https://habr.com/ru/companies/alp_itsm/articles/1012242/

#управление_людьми #управление_персоналом #безопасность #документирование

Как мы учим стажеров разработке на Turbo Script, используя системный подход

Привет, мир! Софья, 5 лет в ERP на Turbo Script, старший разработчик Консист Бизнес Групп. За это время я не раз убеждалась: обучение стажёров — это искусство баланса между академическими знаниями и реальными задачами, где каждая строчка кода может стать либо фундаментом архитектуры, либо техническим долгом. В этой статье поделюсь своим подходом к наставничеству: что брать для перехода от теории к практике и как выстроить обучение так, чтобы стажёр не просто решал задачи, а начинал мыслить системно. Если Вы джун, который только входит в мир продуктовой разработки, или наставник, ищущий подход к обучению, добро пожаловать под кат!

https://habr.com/ru/companies/lansoft_career/articles/992020/

#стажировка_в_it #карьера_программиста #карьера_в_it #учебный_процесс #agile #turbo #script #код #документирование #субд

Книга в Markdown: Автоматическая сборка статического сайта mdBook и файла DOCX с оформлением по ГОСТ

Текст книг, учебных пособий, научно-технических статей, документации, дипломных и курсовых работ часто набирается и редактируется в WYSIWYG-редакторе, таком как Microsoft Word, в том числе вследствие того, что издательства и организации требуют от авторов оформленный по ГОСТ или внутренним стандартам docx-документ. Процесс работы в Microsoft Word и аналогичных редакторах не лишён недостатков: docx-файлы трудно версионировать в git, а для объединения нескольких документов в один придётся перенумеровывать источники, рисунки, таблицы, формулы. Альтернативой docx является LaTeX. Однако работа со стилями в LaTeX простотой и минималистичным синтаксисом не отличается , причём издательства от использования формата docx отказываться не торопятся. А инструменты в духе typst отличаются нестандартным синтаксисом языка для описания документов, причём возможность генерации сайтов в typst имеет пометку «in preview». Markdown — популярный и удобный язык разметки, но это также и очень ограниченный формат. Поэтому задача написания в Markdown сложной технической документации по ГОСТ, научной статьи с автоматической настройкой оформления для заданного издательства или хорошо оформленного онлайн-учебника может показаться неосуществимой. В этой статье рассмотрим способ работы над научно-техническими статьями и книгами в формате Markdown на основе подхода Docs as Code с учётом строгих ограничений на оформление, используемый Петром Советовым @true-grue и мной при подготовке учебных материалов в РТУ МИРЭА. Способ заключается в применении утилиты pandoc для построения дерева абстрактного синтаксиса (AST) Markdown-документа с последующим переписыванием AST набором фильтров на Lua и трансляцией AST в форматы docx и pdf, соответствующие ГОСТ, а также в диалект markdown, совместимый с mdBook , для генерации онлайн-учебника в виде статического сайта. Исходный код книги , написанной с использованием описанного в статье подхода, опубликован на GitHub.

https://habr.com/ru/articles/987982/

#pandoc #markdown #lua #python #документирование #гост #docx #graphviz #mdbook #github

Книга в Markdown: Автоматическая сборка статического сайта mdBook и файла DOCX с оформлением по ГОСТ

Текст книг, учебных пособий, научно-технических статей, документации, дипломных и курсовых работ часто набирается и редактируется в WYSIWYG-редакторе, таком как Microsoft Word, в том числе вследствие того, что издательства и организации требуют от авторов оформленный по ГОСТ или внутренним стандартам docx-документ. Процесс работы в Microsoft Word и аналогичных редакторах не лишён недостатков: docx-файлы трудно версионировать в git, а для объединения нескольких документов в один придётся перенумеровывать источники, рисунки, таблицы, формулы. Альтернативой docx является LaTeX. Однако работа со стилями в LaTeX простотой и минималистичным синтаксисом не отличается , причём издательства от использования формата docx отказываться не торопятся. А инструменты в духе typst отличаются нестандартным синтаксисом языка для описания документов, причём возможность генерации сайтов в typst имеет пометку «in preview». Markdown — популярный и удобный язык разметки, но это также и очень ограниченный формат. Поэтому задача написания в Markdown сложной технической документации по ГОСТ, научной статьи с автоматической настройкой оформления для заданного издательства или хорошо оформленного онлайн-учебника может показаться неосуществимой. В этой статье рассмотрим способ работы над научно-техническими статьями и книгами в формате Markdown на основе подхода Docs as Code с учётом строгих ограничений на оформление, используемый Петром Советовым @true-grue и мной при подготовке учебных материалов в РТУ МИРЭА. Способ заключается в применении утилиты pandoc для построения дерева абстрактного синтаксиса (AST) Markdown-документа с последующим переписыванием AST набором фильтров на Lua и трансляцией AST в форматы docx и pdf, соответствующие ГОСТ, а также в диалект markdown, совместимый с mdBook , для генерации онлайн-учебника в виде статического сайта. Исходный код книги , написанной с использованием описанного в статье подхода, опубликован на GitHub.

https://habr.com/ru/articles/987982/

#pandoc #markdown #lua #python #документирование #гост #docx #graphviz #mdbook #github

Книга в Markdown: Автоматическая сборка статического сайта mdBook и файла DOCX с оформлением по ГОСТ

Текст книг, учебных пособий, научно-технических статей, документации, дипломных и курсовых работ часто набирается и редактируется в WYSIWYG-редакторе, таком как Microsoft Word, в том числе вследствие того, что издательства и организации требуют от авторов оформленный по ГОСТ или внутренним стандартам docx-документ. Процесс работы в Microsoft Word и аналогичных редакторах не лишён недостатков: docx-файлы трудно версионировать в git, а для объединения нескольких документов в один придётся перенумеровывать источники, рисунки, таблицы, формулы. Альтернативой docx является LaTeX. Однако работа со стилями в LaTeX простотой и минималистичным синтаксисом не отличается , причём издательства от использования формата docx отказываться не торопятся. А инструменты в духе typst отличаются нестандартным синтаксисом языка для описания документов, причём возможность генерации сайтов в typst имеет пометку «in preview». Markdown — популярный и удобный язык разметки, но это также и очень ограниченный формат. Поэтому задача написания в Markdown сложной технической документации по ГОСТ, научной статьи с автоматической настройкой оформления для заданного издательства или хорошо оформленного онлайн-учебника может показаться неосуществимой. В этой статье рассмотрим способ работы над научно-техническими статьями и книгами в формате Markdown на основе подхода Docs as Code с учётом строгих ограничений на оформление, используемый Петром Советовым @true-grue и мной при подготовке учебных материалов в РТУ МИРЭА. Способ заключается в применении утилиты pandoc для построения дерева абстрактного синтаксиса (AST) Markdown-документа с последующим переписыванием AST набором фильтров на Lua и трансляцией AST в форматы docx и pdf, соответствующие ГОСТ, а также в диалект markdown, совместимый с mdBook , для генерации онлайн-учебника в виде статического сайта. Исходный код книги , написанной с использованием описанного в статье подхода, опубликован на GitHub.

https://habr.com/ru/articles/987982/

#pandoc #markdown #lua #python #документирование #гост #docx #graphviz #mdbook #github

Книга в Markdown: Автоматическая сборка статического сайта mdBook и файла DOCX с оформлением по ГОСТ

Текст книг, учебных пособий, научно-технических статей, документации, дипломных и курсовых работ часто набирается и редактируется в WYSIWYG-редакторе, таком как Microsoft Word, в том числе вследствие того, что издательства и организации требуют от авторов оформленный по ГОСТ или внутренним стандартам docx-документ. Процесс работы в Microsoft Word и аналогичных редакторах не лишён недостатков: docx-файлы трудно версионировать в git, а для объединения нескольких документов в один придётся перенумеровывать источники, рисунки, таблицы, формулы. Альтернативой docx является LaTeX. Однако работа со стилями в LaTeX простотой и минималистичным синтаксисом не отличается , причём издательства от использования формата docx отказываться не торопятся. А инструменты в духе typst отличаются нестандартным синтаксисом языка для описания документов, причём возможность генерации сайтов в typst имеет пометку «in preview». Markdown — популярный и удобный язык разметки, но это также и очень ограниченный формат. Поэтому задача написания в Markdown сложной технической документации по ГОСТ, научной статьи с автоматической настройкой оформления для заданного издательства или хорошо оформленного онлайн-учебника может показаться неосуществимой. В этой статье рассмотрим способ работы над научно-техническими статьями и книгами в формате Markdown на основе подхода Docs as Code с учётом строгих ограничений на оформление, используемый Петром Советовым @true-grue и мной при подготовке учебных материалов в РТУ МИРЭА. Способ заключается в применении утилиты pandoc для построения дерева абстрактного синтаксиса (AST) Markdown-документа с последующим переписыванием AST набором фильтров на Lua и трансляцией AST в форматы docx и pdf, соответствующие ГОСТ, а также в диалект markdown, совместимый с mdBook , для генерации онлайн-учебника в виде статического сайта. Исходный код книги , написанной с использованием описанного в статье подхода, опубликован на GitHub.

https://habr.com/ru/articles/987982/

#pandoc #markdown #lua #python #документирование #гост #docx #graphviz #mdbook #github

Топ инструментов ИИ для системного аналитика

Недавно я участвовал в круглом столе на тему «аналитики против искусственного интеллекта». Это обсуждение вдохновило меня на более предметный разговор о том, почему нейронные сети — это не противник, а полезный инструмент, который реально экономит время. Меня зовут Владимир Бурмистров, я главный системный аналитик в IT-холдинге Т1. В отрасли я уже 18 лет — застал и времена адаптации под Internet Explorer 6, и приход нейросетей. И я могу уверенно сказать: благодаря нейросетям я ускоряю свою работу примерно на 30%. Как именно? Давайте разбираться по порядку.

https://habr.com/ru/articles/984904/

#Инструменты_ИИ #Экономия_времени #Искусственный_интеллект #ии #ииассистент #Системный_аналитик #Документирование #Эффективность #Продуктивность

Топ инструментов ИИ для системного аналитика

Недавно я участвовал в круглом столе на тему «аналитики против искусственного интеллекта». Это обсуждение вдохновило меня на более предметный разговор о том, почему нейронные сети — это не противник, а полезный инструмент, который реально экономит время. Меня зовут Владимир Бурмистров, я главный системный аналитик в IT-холдинге Т1. В отрасли я уже 18 лет — застал и времена адаптации под Internet Explorer 6, и приход нейросетей. И я могу уверенно сказать: благодаря нейросетям я ускоряю свою работу примерно на 30%. Как именно? Давайте разбираться по порядку.

https://habr.com/ru/articles/984904/

#Инструменты_ИИ #Экономия_времени #Искусственный_интеллект #ии #ииассистент #Системный_аналитик #Документирование #Эффективность #Продуктивность

Топ инструментов ИИ для системного аналитика

Недавно я участвовал в круглом столе на тему «аналитики против искусственного интеллекта». Это обсуждение вдохновило меня на более предметный разговор о том, почему нейронные сети — это не противник, а полезный инструмент, который реально экономит время. Меня зовут Владимир Бурмистров, я главный системный аналитик в IT-холдинге Т1. В отрасли я уже 18 лет — застал и времена адаптации под Internet Explorer 6, и приход нейросетей. И я могу уверенно сказать: благодаря нейросетям я ускоряю свою работу примерно на 30%. Как именно? Давайте разбираться по порядку.

https://habr.com/ru/articles/984904/

#Инструменты_ИИ #Экономия_времени #Искусственный_интеллект #ии #ииассистент #Системный_аналитик #Документирование #Эффективность #Продуктивность

Топ инструментов ИИ для системного аналитика

Недавно я участвовал в круглом столе на тему «аналитики против искусственного интеллекта». Это обсуждение вдохновило меня на более предметный разговор о том, почему нейронные сети — это не противник, а полезный инструмент, который реально экономит время. Меня зовут Владимир Бурмистров, я главный системный аналитик в IT-холдинге Т1. В отрасли я уже 18 лет — застал и времена адаптации под Internet Explorer 6, и приход нейросетей. И я могу уверенно сказать: благодаря нейросетям я ускоряю свою работу примерно на 30%. Как именно? Давайте разбираться по порядку.

https://habr.com/ru/articles/984904/

#Инструменты_ИИ #Экономия_времени #Искусственный_интеллект #ии #ииассистент #Системный_аналитик #Документирование #Эффективность #Продуктивность

Новая жизнь репозитория: архитектурные решения для успешной документации

Привет, Хабр! Я Артём Клещев, технический писатель в СберТехе. Я пишу документацию к продукту Platform V DropApp — решению для управления контейнерными приложениями. Наша команда работает в парадигме Docs-as-Code. Мы столкнулись с проблемой: при каждом изменении продукта нам нужно было менять документацию сразу в нескольких репозиториях — для каждого исполнения продукта. Но мы нашли решение, как оптимизировать процесс. И хотим поделиться рекомендациями по ведению единого источника в Docs-as-Code — будет полезно тем, кто хочет шаблонизировать документацию и сэкономить время для творческих задач. В статье покажу, как построить удобную архитектуру репозитория продукта с применением шаблонов и MyST-разметки в парадигме Docs-as-Code. Расскажу, как вместо поддержки нескольких разрозненных комплектов документации создать библиотеку шаблонов с общим контентом. Надеюсь, что опыт нашей команды поможет вам избежать ошибок и лишних шагов.

https://habr.com/ru/companies/sberbank/articles/975836/

#сбертех #platform_v #dropapp #документация #документирование #docsascode

Как документировать GraphQL API: полное руководство для технических писателей

GraphQL API — это мощно, но как его документировать, чтобы разработчики остались довольны? В этой статье — готовый план действий. Мы начнём со сравнения GraphQL и REST, затем покажем, как с помощью комментариев и примеров кода превратить схему в наглядное руководство. Вы узнаете, как улучшить GraphiQL Playground подсветкой синтаксиса и создать статический справочник, если Playground недоступен. В конце вас ждёт учебный репозиторий для тренировок на реальном API.

https://habr.com/ru/companies/flant/articles/971198/

#graphql #техническая_документация #техпис #graphql_api #playground #документирование #документирование_проектов #rest #rest_api #api

Как документировать GraphQL API: полное руководство для технических писателей

GraphQL API — это мощно, но как его документировать, чтобы разработчики остались довольны? В этой статье — готовый план действий. Мы начнём со сравнения GraphQL и REST, затем покажем, как с помощью комментариев и примеров кода превратить схему в наглядное руководство. Вы узнаете, как улучшить GraphiQL Playground подсветкой синтаксиса и создать статический справочник, если Playground недоступен. В конце вас ждёт учебный репозиторий для тренировок на реальном API.

https://habr.com/ru/companies/flant/articles/971198/

#graphql #техническая_документация #техпис #graphql_api #playground #документирование #документирование_проектов #rest #rest_api #api

Как документировать GraphQL API: полное руководство для технических писателей

GraphQL API — это мощно, но как его документировать, чтобы разработчики остались довольны? В этой статье — готовый план действий. Мы начнём со сравнения GraphQL и REST, затем покажем, как с помощью комментариев и примеров кода превратить схему в наглядное руководство. Вы узнаете, как улучшить GraphiQL Playground подсветкой синтаксиса и создать статический справочник, если Playground недоступен. В конце вас ждёт учебный репозиторий для тренировок на реальном API.

https://habr.com/ru/companies/flant/articles/971198/

#graphql #техническая_документация #техпис #graphql_api #playground #документирование #документирование_проектов #rest #rest_api #api

Как документировать GraphQL API: полное руководство для технических писателей

GraphQL API — это мощно, но как его документировать, чтобы разработчики остались довольны? В этой статье — готовый план действий. Мы начнём со сравнения GraphQL и REST, затем покажем, как с помощью комментариев и примеров кода превратить схему в наглядное руководство. Вы узнаете, как улучшить GraphiQL Playground подсветкой синтаксиса и создать статический справочник, если Playground недоступен. В конце вас ждёт учебный репозиторий для тренировок на реальном API.

https://habr.com/ru/companies/flant/articles/971198/

#graphql #техническая_документация #техпис #graphql_api #playground #документирование #документирование_проектов #rest #rest_api #api

[Перевод] Documentation-Driven Development

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

https://habr.com/ru/articles/965306/

#Разработка #документирование

Размышления о документации

Вряд ли найдётся кто-либо, кто в здравом уме и ясной памяти будет отрицать необходимость документации. Любой продукт имеет (или должен иметь) свою документацию. Как минимум – инструкцию о том, как этим продуктом пользоваться. Производители почти всегда указывают – « прежде чем начать пользоваться нашим продуктом, внимательно ознакомьтесь с инструкцией ». Но дело почти никогда не ограничивается инструкцией пользователя. Производители также составляют и другую документацию – техническую, эксплуатационную. Но ЧТО же должен создавать автор документации? Что должна в себя включать документация, когда, на каком этапе и в каком объёме она должна создаваться, ЧТО она должна содержать, когда, кому и при каких обстоятельствах она может потребоваться? В данной статье мы и поразмышляем об этом... Читать статью

https://habr.com/ru/articles/958076/

#документирование #документация #документация_проекта #документирование_проектов #управление_проектом #управление_продуктом #техническая_документация #технический_писатель

Размышления о документации

Вряд ли найдётся кто-либо, кто в здравом уме и ясной памяти будет отрицать необходимость документации. Любой продукт имеет (или должен иметь) свою документацию. Как минимум – инструкцию о том, как этим продуктом пользоваться. Производители почти всегда указывают – « прежде чем начать пользоваться нашим продуктом, внимательно ознакомьтесь с инструкцией ». Но дело почти никогда не ограничивается инструкцией пользователя. Производители также составляют и другую документацию – техническую, эксплуатационную. Но ЧТО же должен создавать автор документации? Что должна в себя включать документация, когда, на каком этапе и в каком объёме она должна создаваться, ЧТО она должна содержать, когда, кому и при каких обстоятельствах она может потребоваться? В данной статье мы и поразмышляем об этом... Читать статью

https://habr.com/ru/articles/958076/

#документирование #документация #документация_проекта #документирование_проектов #управление_проектом #управление_продуктом #техническая_документация #технический_писатель

Размышления о документации

Вряд ли найдётся кто-либо, кто в здравом уме и ясной памяти будет отрицать необходимость документации. Любой продукт имеет (или должен иметь) свою документацию. Как минимум – инструкцию о том, как этим продуктом пользоваться. Производители почти всегда указывают – « прежде чем начать пользоваться нашим продуктом, внимательно ознакомьтесь с инструкцией ». Но дело почти никогда не ограничивается инструкцией пользователя. Производители также составляют и другую документацию – техническую, эксплуатационную. Но ЧТО же должен создавать автор документации? Что должна в себя включать документация, когда, на каком этапе и в каком объёме она должна создаваться, ЧТО она должна содержать, когда, кому и при каких обстоятельствах она может потребоваться? В данной статье мы и поразмышляем об этом... Читать статью

https://habr.com/ru/articles/958076/

#документирование #документация #документация_проекта #документирование_проектов #управление_проектом #управление_продуктом #техническая_документация #технический_писатель

Размышления о документации

Вряд ли найдётся кто-либо, кто в здравом уме и ясной памяти будет отрицать необходимость документации. Любой продукт имеет (или должен иметь) свою документацию. Как минимум – инструкцию о том, как этим продуктом пользоваться. Производители почти всегда указывают – « прежде чем начать пользоваться нашим продуктом, внимательно ознакомьтесь с инструкцией ». Но дело почти никогда не ограничивается инструкцией пользователя. Производители также составляют и другую документацию – техническую, эксплуатационную. Но ЧТО же должен создавать автор документации? Что должна в себя включать документация, когда, на каком этапе и в каком объёме она должна создаваться, ЧТО она должна содержать, когда, кому и при каких обстоятельствах она может потребоваться? В данной статье мы и поразмышляем об этом... Читать статью

https://habr.com/ru/articles/958076/

#документирование #документация #документация_проекта #документирование_проектов #управление_проектом #управление_продуктом #техническая_документация #технический_писатель

Документирование архитектуры

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

https://habr.com/ru/articles/957348/

#архитектура #документация #документирование

Примеры для вдохновения — оформление README

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

https://habr.com/ru/companies/mws/articles/919184/

#mws #readme #readmemd #документация #документирование

Примеры для вдохновения — оформление README

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

https://habr.com/ru/companies/mws/articles/919184/

#mws #readme #readmemd #документация #документирование

Примеры для вдохновения — оформление README

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

https://habr.com/ru/companies/mws/articles/919184/

#mws #readme #readmemd #документация #документирование

Примеры для вдохновения — оформление README

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

https://habr.com/ru/companies/mws/articles/919184/

#mws #readme #readmemd #документация #документирование

Документация как навык выживания

Дисклеймер для тех, кто не смотрел «Друзей» Моника Геллер — персонаж культового ситкома 90-х, безумно одержимая порядком. Её чек-листы для чек-листов, лейблы на лейблах и фетиш сортировки по цвету и размеру превратили её в мем про педантизм. Но именно Моника в сериале всегда вытаскивала друзей из провалов: когда нужно было за 3 часа организовать свадьбу, найти документы за 5 лет или просто понять, кто последний брал фондюшницу. В реальной жизни мы живём не в квартире с purple дверью, но законы Моники работают лучше любого скрам-майнд-сета.

https://habr.com/ru/articles/935906/

#документация #документирование #база_знаний #структуры_данных #документация_это_легко

Автоматизированное документирование баз данных на Markdown

В работе с базами данных ключевым аспектом является не только отслеживание изменений в их структуре, но и подробная документация таблиц и их полей. Это особенно важно для проектов с быстро изменяющейся архитектурой, где ясность и точность данных играют решающую роль. Например, в крупных веб-приложениях часто требуется фиксировать новые таблицы, обновления полей или удаление устаревших элементов. Для решения данной задачи разработаны два PHP-скрипта , предназначенные для работы с PostgreSQL . Эти скрипты выполняют две основные функции: 1. Сравнение старой и новой структуры базы данных с выявлением добавленных, удалённых и изменённых таблиц. 2. Создание Markdown-документации, которая содержит подробное описание назначения таблиц и характеристик их полей, что делает изменения в структуре базы данных прозрачными для разработчиков.

https://habr.com/ru/companies/ppr/articles/883616/

#markdown #документирование #postgresql #базы_данных #phpскрипты #скрипты

От Docs as Code к Everything as Code: как Gramax меняет работу с документацией

Привет, Хабр! Меня зовут Катя, я лидирую Gramax , open-source платформу для управления технической документацией. Однажды мы с коллегами утонули в хаосе рабочих документов: без версий, без согласований, без истории принятых решений. Это подтолкнуло нас к созданию Gramax — инструмента, который интегрирует документацию в процесс разработки, делая его прозрачным и управляемым. В этой статье расскажу, как Gramax помогает на каждом этапе разработки ПО. Как перейти к документированию в подходе Docs as Code и шагнуть дальше — к Everything as Code. Интересно, давай!

https://habr.com/ru/articles/910716/

#сезон_open_source #docs_as_code #everything_as_code #adr #аналитика #анализ_и_проектирование_систем #документирование #документация_проекта #документация_на_по

От Docs as Code к Everything as Code: как Gramax меняет работу с документацией

Привет, Хабр! Меня зовут Катя, я лидирую Gramax , open-source платформу для управления технической документацией. Однажды мы с коллегами утонули в хаосе рабочих документов: без версий, без согласований, без истории принятых решений. Это подтолкнуло нас к созданию Gramax — инструмента, который интегрирует документацию в процесс разработки, делая его прозрачным и управляемым. В этой статье расскажу, как Gramax помогает на каждом этапе разработки ПО. Как перейти к документированию в подходе Docs as Code и шагнуть дальше — к Everything as Code. Интересно, давай!

https://habr.com/ru/articles/910716/

#сезон_open_source #docs_as_code #everything_as_code #adr #аналитика #анализ_и_проектирование_систем #документирование #документация_проекта #документация_на_по

От Docs as Code к Everything as Code: как Gramax меняет работу с документацией

Привет, Хабр! Меня зовут Катя, я лидирую Gramax , open-source платформу для управления технической документацией. Однажды мы с коллегами утонули в хаосе рабочих документов: без версий, без согласований, без истории принятых решений. Это подтолкнуло нас к созданию Gramax — инструмента, который интегрирует документацию в процесс разработки, делая его прозрачным и управляемым. В этой статье расскажу, как Gramax помогает на каждом этапе разработки ПО. Как перейти к документированию в подходе Docs as Code и шагнуть дальше — к Everything as Code. Интересно, давай!

https://habr.com/ru/articles/910716/

#сезон_open_source #docs_as_code #everything_as_code #adr #аналитика #анализ_и_проектирование_систем #документирование #документация_проекта #документация_на_по

От Docs as Code к Everything as Code: как Gramax меняет работу с документацией

Привет, Хабр! Меня зовут Катя, я лидирую Gramax , open-source платформу для управления технической документацией. Однажды мы с коллегами утонули в хаосе рабочих документов: без версий, без согласований, без истории принятых решений. Это подтолкнуло нас к созданию Gramax — инструмента, который интегрирует документацию в процесс разработки, делая его прозрачным и управляемым. В этой статье расскажу, как Gramax помогает на каждом этапе разработки ПО. Как перейти к документированию в подходе Docs as Code и шагнуть дальше — к Everything as Code. Интересно, давай!

https://habr.com/ru/articles/910716/

#сезон_open_source #docs_as_code #everything_as_code #adr #аналитика #анализ_и_проектирование_систем #документирование #документация_проекта #документация_на_по

От xWiki к static-HTML. Как мы документацию «переезжали»

Документация в компании HOSTKEY состоит из двух частей: внутренней, которая ведется и дополняется как силами наших технических писателей, так и сотрудниками отделов, для которых она предназначена, и внешней, клиентской. До недавнего времени мы и для внутренней, и для внешней документации использовали xWiki. И если для внутренней документации ее применение оправдано, то для внешней xWiki не самое оптимальное решение: внешнюю документацию создают максимум два–три человека, регистрация дополнительных пользователей не нужна, на xWiki постоянно идут атаки спам-ботов, а изменение структуры документации, переименование, масс-правки, изменение оформления и некоторые другие вещи требуют или правок непосредственно в базе данных, или достаточно много телодвижений. Из плюсов — визуальный редактор, возможность импорта/экспорта статей в формате OpenDocument и гибкая настройка прав. Поэтому было решено для внешней клиентской документации переехать на новый движок, и выбор пал на Material for MkDocs . Весь переезд у нас занял от проработки структуры и рефакторинга до непосредственно переноса и перевода части статей (английская версия отставала от русской) два месяца.

https://habr.com/ru/companies/hostkey/articles/794040/

#StaticHTML #Material_for_MkDocs #wiki #документация #документирование #база_знаний

5 причин, почему пользователи терпеть ненавидят вашу документацию [и как это исправить]

«Ваша документация — отстой!», «Я её никогда не читаю, всё равно там ерунда написана!», «Эти документаторы опять всё напутали», «Да любая нейросеть быстро напишет всё это в сто раз лучше», «Там никогда не найти ничего нужного», «А разве у нас есть документация?»... Обратная связь от читателей-пользователей далеко не всегда бывает конструктивной и вдохновляющей. Почему же так получается? Маловероятно, что кто-то из технических писателей хочет специально выдать плохой документ. Скорее наоборот — авторы изо всех сил стараются, чтобы документация была полезной, понятной и удобной. Но, несмотря на все усилия, идеальный результат получается далеко не всегда. Давайте разберём пять основных претензий читателей к технической документации, и подумаем, что со всем этим делать.

https://habr.com/ru/articles/811461/

#документация #документация_кода #документация_проекта #технические_писатели #документирование #пользовательская_документация #технология_единого_источника #проверка_документации #техническая_документация #обратная_связь

Разработка требований к ПО с помощью Markdown, Git и Obsidian

Пошаговое руководство по использованию Git, Obsidian, Markdown и любимого IDE для разработки требований и трассируемого в них программного кода.

https://habr.com/ru/articles/927152/

#требования_заказчика #комментарии_в_коде #трассировка_требований #git #obsidian #версионность #версионирование #версионность_кода #документирование #документация_проекта

Как превратить бизнес-требования в эффективную схему БД без жертв

Научимся превращать бизнес-требования в рабочую схему БД и документировать ключевые решения! Без недопонимания, технического долга и смс.

https://habr.com/ru/articles/920916/

#проектирование_бд #документирование #логическая_модель_данных #физическая_модель_данных

Эффективное внедрение инструкций в бизнес: почему это важно и как добиться успеха

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

https://habr.com/ru/articles/861508/

#управление_командой #управление_персоналом #инструкция #документация #документирование #документооборот #эффективность_работы

Встречают по README — что нужно знать о документации

Сокращение времени на поиск информации — задача, о которой говорят непростительно мало. Эту задачу должны решать отдельные разработчики и, в целом, компании. Например, CloudMTS

https://habr.com/ru/companies/cloud_mts/articles/811857/

#README #документация #документирование #код

СТОИКИ, visibility, ИПР и другие «витамины роста». 9+ ключевых советов про карьеру от техписов

На прошлой неделе мы в «Лаборатории Касперского» провели онлайн-митап, в рамках которого спикеры из различных компаний рассмотрели карьеру технического писателя как со стороны самого сотрудника (профессиональное развитие, выход на повышение, шифтинг в смежную специальность), так и со стороны нанимающих менеджеров (как найти стажера, как грамотно сформулировать требования к кандидату, как выстроить систему адаптации и что делать, если команда резко увеличилась). Здесь в посте — краткая выжимка эфира в девяти ключевых тезисах, собранных из докладов всех спикеров. Если же вам интересно послушать полные выступления, а также ответы на волнующие зрителей (и, скорее всего, вас тоже) вопросы, посмотрите запись митапа по этой ссылке или в виджете ниже. Тем более что часть тезисов о развитии, повышении и структурных изменениях в команде будет применима не только к разработке документации, но и к другим сферам.

https://habr.com/ru/companies/kaspersky/articles/800319/

#программирование #разработка #оптимизация #производительность #документация #техническая_документация #технический_писатель #confluence #документирование #база_знаний #технические_писатели #стандарты #софт #карьера #работа #карьера_в_it #карьера_в_itиндустрии #itкомпании #карьера_итспециалиста #hr #персонал #управление_людьми #сотрудники #управление_командой #управление_персоналом #собеседование #обучение #образование #курсы #учебный_процесс #учебный_процесс_в_it

Приглашаем на онлайновый митап про карьеру техписа: наём, развитие, треки

В среду, 6 марта, в 16 часов (МСК) мы проведем онлайновый митап под названием « Kaspersky Tech Fest. Карьера техписа: наём, развитие, треки ». Спикерами митапа будут технические писатели, а также тимлиды команд техписов и руководители отделов технической документации из топовых компаний. Коллеги рассмотрят карьеру и развитие технического писателя с разных сторон: от поиска и адаптации нового сотрудника (включая стажера без опыта) до источников профессионального роста и возможностей повышения.

https://habr.com/ru/companies/kaspersky/articles/795071/

#программирование #разработка #оптимизация #производительность #документация #техническая_документация #технический_писатель #confluence #документирование #база_знаний #технические_писатели #стандарты #софт #карьера #работа #карьера_в_it #карьера_в_itиндустрии #itкомпании #карьера_итспециалиста #hr #персонал #управление_людьми #сотрудники #управление_командой #управление_персоналом #собеседование #обучение #образование #курсы #учебный_процесс #учебный_процесс_в_it

Quick & worldwide: как мы ускорили DocLoc-релизы и апдейты для 34 локализаций

Наши потребительские мобильные продукты уникальны тем, что распространяются в более чем 100 странах на 34 языках — возможно, рекордное значение в российской IT-индустрии. В основном лишь считанные продукты отдельных компаний переводятся на десяток-другой языков; у нас же масса флагманов, которые переводятся на все 34. И конечно, если бы мы в группе разработки документации и локализаций (Doc&Loc) переводили каждую локаль «от корки до корки» по отдельности и никак это не оптимизировали, то пожалуй, никаких рекордов бы не было. Меня зовут Никита Авилов, я — технический писатель в группе Doc&Loc Mac & Mobile «Лаборатории Касперского». В этой статье расскажу, как именно мы выстроили работу внутри команды, а также кроссфункциональное взаимодействие с другими подразделениями, чтобы меньшими усилиями раскатывать наши продукты на такое количество локалей.

https://habr.com/ru/companies/kaspersky/articles/777296/

#локализация #перевод #localization #локализация_приложений #translation #локализация_интерфейса #переводы #документация #техническая_документация #технический_писатель #документирование #doc #управление_проектами #проектирование #интерфейсы #ux #дизайн #ui #юзабилити #дизайн_интерфейсов #ux/ui #продуктовый_дизайн #интерфейс #пользовательские_интерфейсы #терминология #термины #itюрист #терминология_it #тестирование #информационные_технологии

От xWiki к static-HTML. Как мы документацию «переезжали»

Документация в компании HOSTKEY состоит из двух частей: внутренней, которая ведется и дополняется как силами наших технических писателей, так и сотрудниками отделов, для которых она предназначена, и внешней, клиентской. До недавнего времени мы и для внутренней, и для внешней документации использовали xWiki. И если для внутренней документации ее применение оправдано, то для внешней xWiki не самое оптимальное решение: внешнюю документацию создают максимум два–три человека, регистрация дополнительных пользователей не нужна, на xWiki постоянно идут атаки спам-ботов, а изменение структуры документации, переименование, масс-правки, изменение оформления и некоторые другие вещи требуют или правок непосредственно в базе данных, или достаточно много телодвижений. Из плюсов — визуальный редактор, возможность импорта/экспорта статей в формате OpenDocument и гибкая настройка прав. Поэтому было решено для внешней клиентской документации переехать на новый движок, и выбор пал на Material for MkDocs . Весь переезд у нас занял от проработки структуры и рефакторинга до непосредственно переноса и перевода части статей (английская версия отставала от русской) два месяца.

https://habr.com/ru/companies/hostkey/articles/794040/

#StaticHTML #Material_for_MkDocs #wiki #документация #документирование #база_знаний

5 причин, почему пользователи терпеть ненавидят вашу документацию [и как это исправить]

«Ваша документация — отстой!», «Я её никогда не читаю, всё равно там ерунда написана!», «Эти документаторы опять всё напутали», «Да любая нейросеть быстро напишет всё это в сто раз лучше», «Там никогда не найти ничего нужного», «А разве у нас есть документация?»... Обратная связь от читателей-пользователей далеко не всегда бывает конструктивной и вдохновляющей. Почему же так получается? Маловероятно, что кто-то из технических писателей хочет специально выдать плохой документ. Скорее наоборот — авторы изо всех сил стараются, чтобы документация была полезной, понятной и удобной. Но, несмотря на все усилия, идеальный результат получается далеко не всегда. Давайте разберём пять основных претензий читателей к технической документации, и подумаем, что со всем этим делать.

https://habr.com/ru/articles/811461/

#документация #документация_кода #документация_проекта #технические_писатели #документирование #пользовательская_документация #технология_единого_источника #проверка_документации #техническая_документация #обратная_связь

5 причин, почему пользователи терпеть ненавидят вашу документацию [и как это исправить]

«Ваша документация — отстой!», «Я её никогда не читаю, всё равно там ерунда написана!», «Эти документаторы опять всё напутали», «Да любая нейросеть быстро напишет всё это в сто раз лучше», «Там никогда не найти ничего нужного», «А разве у нас есть документация?»... Обратная связь от читателей-пользователей далеко не всегда бывает конструктивной и вдохновляющей. Почему же так получается? Маловероятно, что кто-то из технических писателей хочет специально выдать плохой документ. Скорее наоборот — авторы изо всех сил стараются, чтобы документация была полезной, понятной и удобной. Но, несмотря на все усилия, идеальный результат получается далеко не всегда. Давайте разберём пять основных претензий читателей к технической документации, и подумаем, что со всем этим делать.

https://habr.com/ru/articles/811461/

#документация #документация_кода #документация_проекта #технические_писатели #документирование #пользовательская_документация #технология_единого_источника #проверка_документации #техническая_документация #обратная_связь

Quick & worldwide: как мы ускорили DocLoc-релизы и апдейты для 34 локализаций

Наши потребительские мобильные продукты уникальны тем, что распространяются в более чем 100 странах на 34 языках — возможно, рекордное значение в российской IT-индустрии. В основном лишь считанные продукты отдельных компаний переводятся на десяток-другой языков; у нас же масса флагманов, которые переводятся на все 34. И конечно, если бы мы в группе разработки документации и локализаций (Doc&Loc) переводили каждую локаль «от корки до корки» по отдельности и никак это не оптимизировали, то пожалуй, никаких рекордов бы не было. Меня зовут Никита Авилов, я — технический писатель в группе Doc&Loc Mac & Mobile «Лаборатории Касперского». В этой статье расскажу, как именно мы выстроили работу внутри команды, а также кроссфункциональное взаимодействие с другими подразделениями, чтобы меньшими усилиями раскатывать наши продукты на такое количество локалей.

https://habr.com/ru/companies/kaspersky/articles/777296/

#локализация #перевод #localization #локализация_приложений #translation #локализация_интерфейса #переводы #документация #техническая_документация #технический_писатель #документирование #doc #управление_проектами #проектирование #интерфейсы #ux #дизайн #ui #юзабилити #дизайн_интерфейсов #ux/ui #продуктовый_дизайн #интерфейс #пользовательские_интерфейсы #терминология #термины #itюрист #терминология_it #тестирование #информационные_технологии