Статьи

Традиционный бумажный формат неизбежно уступает место инновационным решениям. Интерактивное электронное техническое руководство (ИЭТР) - это передовой инструмент нового поколения, призванный кардинально изменить подход к управлению технической информацией.

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

В сфере проектирования ПО существует распространенное заблуждение, что техдокументация - это лишь бюрократическая формальность, тормозящая рабочий процесс. Однако многие стандарты качества, включая ISO 9000, CMMI и COBIT, придают ей огромное значение. В то же время, сторонники "быстрых" методологий стремятся свести документирование к минимуму. Оптимальный подход, как правило, находится посередине между этими крайностями.

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

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

Система Confluence – результат деятельности австралийской компании Atlassian, создающей ПО для управления разработкой ПО. Известность компании
принесли два продукта: Jira и Confluence. Первый продукт обеспечивает управление проектами на любой стадии разработки, а второй – нацелен на обмен специалистами важной информацией по проекту, организации базы знаний.

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

Markdown – облегченный язык текстовой разметки. С чем связано появления данного языка? В 2000-е гг. удобных платформ для размещения контента не было: для публикации отформатированного текста приходилось обращаться к HTML разметке. Основным минусом этого языка была необходимость вручную прописывать большое количество тегов. Это затрудняло процесс написания и исправления текста.

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

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

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

Как будет выглядеть интерфейс продукта? Какие в нем будут структурные элементы? Подобные вопросы возникают у заказчика на первых этапах разработки программного обеспечения. Ответить на них разработчик может при помощи прототипов.

Существуют инструменты, позволяющие собирать комментарии к коду, а на основе их создавать документацию. Какие они бывают и в чем их особенность?

Разработка программной документации – длительный процесс, требующий особой внимательности. Технические писатели и разработчики ищут способы упростить данный процесс при помощи специальных инструментов. Один из таких инструментов – Dr. Explain. В чем же особенность данного продукта?

Как эффективно использовать API? На этот вопрос ответит API-документация. В ней содержится информация, необходимая для работы с API и подробные сведения о функциях и типах возвращаемых значений.

Что позволяет пользователю получить базовую информацию по регулировке и применению
программы? Конечно, справочная система, а точнее, Help-справка. Подробнее о создании файлов-справок узнайте из нашей статьи.

При подготовке документации группой специалистов важно придерживаться единообразия в оформлении и стиле изложения. Помощником в таком случае выступает стайлгайд.

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

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

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