Рубрика «документация» - 6

в 13:28, , рубрики: .net, big data в документации, devexpress, Анализ и проектирование систем, библиотеки, Блог компании DevExpress, документация, документирование кода

Ворочаем большими объёмами документации - 1

  • А как вы поддерживаете справку по API в актуальном состоянии?
  • Как можно организовать и хранить локализованные версии?
  • Вы проверяете текст на наличие недопустимых символов и на валидность разметки?
  • Как организовать проверку (вычитку) топиков?

Эти и другие вопросы я часто слышу от технических писателей на конференциях. Для небольших объёмов документации достаточно вручную пересмотреть документы и обновить/подставить/поправить всё, что нужно. А если объёмы документации выросли?

Наша документация выросла до более чем 154 000 документов только по .NET-линейке продуктов, из них около 140 000 документов — это справка по API. Около 8-10 тысяч топиков добавляются каждый мажорный релиз (т.е. дважды в год). В этой статье я расскажу как мы справляемся с такими объёмами.

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

Читать полностью »

в 10:58, , рубрики: stackoverflow, документация, документирование кода, Программирование, сопровождение

Вчера произошло достаточно значимое событие на рынке разработки. Точнее в сфере поддержки и сопровождении программных продуктов. StackOverflow запустил раздел документация. Почему это важно?

Читать полностью »

в 18:28, , рубрики: документация, подготовка документации, техдокументация, техническая документация, технический текст, Учебный процесс в IT, метки: , ,

Введение

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

Эти правила — не моё собственное изобретение. Скорее, я просто сформулировал их из того опыта, который появился благодаря общению со многими талантливыми техническими и литературными редакторами за более чем десять лет работы. Всё, что я понял в этом деле, сформировалось потому, что другие показали мне путь. У меня не находится достаточно слов, чтобы выразить им в полной мере мою благодарность.

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

Итак — эти 7 правил:

  1. Скука убивает
  2. Прежде чем начать, выясните точно для себя, какие действия вы ожидаете от читателя, осилившего ваш труд
  3. Пишите в соответствии с правильно сформированной структурой
  4. Избегайте неоднозначных местоимений
  5. Ясность = иллюстрации + слова
  6. Когда имеете дело с понятиями, концепциями и т.п., используйте логическую иллюстрацию и пример
  7. Не опасайтесь переделок

Читать полностью »

в 7:54, , рубрики: Gamedev, gamedevelopment, indiedev, документация, разработка игр, разработка игры

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

Документация — основа игры - 1
Читать полностью »

в 21:04, , рубрики: azure, iis, Microsoft Azure, SSL, ssl сертификаты, Блог компании ABBYY, документация, ит-инфраструктура, Облачные вычисления, облачные сервисы

Исправлена серьезная ошибка в официальной документации по настройке SSL в web-ролях Microsoft Azure - 1
Хорошие новостиTM: есть небольшое, но важное развитие сюжета из этого поста, где много букв и долгая история, которая могла отвлечь часть целевой аудитории от необходимости проверить и исправить настройки. После вливания освежающих пул-запросов была обновлена официальная документация, показывающая, как правильно настраивать SSL в веб-ролях Microsoft Azure — один и два. Исправлена серьезная ошибка в примерах настроек.

Если вы разрабатываете или сопровождаете облачный сервис с веб-ролью, самое время проверить, что настройки SSL указаны правильно и вас не настигнет в самый неподходящий момент волна недовольства пользователей, у которых КРАЙНЕ НЕОЖИДАННО без ясных причин перестало устанавливаться защищенное соединение с вашим сервисом.Читать полностью »

в 18:31, , рубрики: бэклог, документация, управление проектами, управление разработкой, управление требованиями

Зачем, кому это нужно, чем это сделать

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

  • видеть связь: требование➝вопрос➝изменение в требовании➝новое требование;
  • избежать дублирования требований/вопросов;
  • отследить задействованные в реализации системы (от обратного: чтобы представитель каждой системы видел требования, реализация которых хоть как-то касается его системы);
  • получать подтверждение по каждому требованию — что да, требование понято и зафиксировано верно, что реализация возможна;
  • проследить связь с требованиями другого, очень похожего на наш проект проекта — чтобы иметь знание, что вот это уже там реализовано, и мы будем просто использовать сделанные наработки;

Да и вообще.
Читать полностью »

в 4:30, , рубрики: .net, api, autorest, client-server, javascript, rest, restful api, swagger, TypeScript, Блог компании EastBanc Technologies, документация

Введение

В данной статье рассматривается вопрос о том, как реализовать обмен типизированными сообщениями между Back-End на основе ASP.NET Web API и Front-End, созданного с использованием TypeScript. Это приобретает особенное значение при работе над объёмными проектами, и тем-более важно, если команда является распределенной. Например, когда Back-End и Front-End разработчики работают из разных мест, в разных часовых поясах, и не всегда имеют возможность проконтактировать и обсудить что-либо. В этом случае отслеживание изменений представляет кропотливую работу, которая может быть чревата множеством трудноуловимых ошибок.

Для автора статьи, как для человека, который пришел к разработке Front-End со стороны WPF и Silverlight, большой проблемой, стало отсутствие статической типизации. Сколько раз вместо того чтобы сложить “2” и “2” складывал “2” и “Функцию возвращающую 2”, или передавал DOM объект вместо его jQuery обертки. Появление статических анализаторов кода, таких как JSLint, несколько облегчило проблему, но настоящим прорывом, особенно в командной разработке, для нас стал TypeScript.

На пути к полной типизации с TypeScript, Swashbuckle и AutoRest - 1
Читать полностью »

в 15:33, , рубрики: документация, Разработка веб-сайтов, Разработка под e-commerce, управление разработкой, управление требованиями, функциональные требования

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

Речь идёт об организации готовых требований (требования уже получены и сформулированы, и теперь с ними ведётся работа). И в данном контексте требование — это описание некой функциональности (в моём случае — к сайту), на языке, понятном разработчику, заказчику, простому смертному, дающее представление о том, «как это должно работать».

То, что написано ниже, — не есть истина в последней инстанции, это лишь описание проблем, с которыми команда разработки сталкивается в работе с требованиями ежедневно, и инструменты, с помощью которых можно их решить.
Читать полностью »

в 10:44, , рубрики: csv, ERP-системы, jinja2, latex, python, XML, визуализация данных, документация, документирование

Работая над проектами связанными с авионикой мне потребовалось оформить несколько комплектов документации с полным описанием проекта. Также следовало учитывать требования многих ГОСТов на оформление и на содержание документации, таких как ЕСПД, КТ-178B и других.

Описание должно было в себя включать:

  • Планы разработки ПО
  • Требования к ПО
  • Описание реализации требований к ПО
  • Таблицы трассируемости(соответствия) требований к ПО и реализации
  • Описание тестов на ПО (Примеры и процедуры верификации ПО)
  • Таблицы трассируемости(соответствия) требований к ПО и тестов
  • Отчет об обнаруженных проблемах
  • Указатель конфигурации(описание версии ПО и совместимости со сторонним ПО и оборудованием)

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

Автоматизация оформления документации - 1

Далее в статье я расскажу как я решил эту проблему.

Читать полностью »

в 17:36, , рубрики: c++, clang, game development, mac os x, SFML, xcode, документация, Локализация продуктов, перевод, Программирование, установка

SFML и Xcode (Mac OS X) - 1

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

1...567...10...10
Главная   |  Архив новостей  |   Android  |   Google  |   Apple  |   Microsoft  |   Информационная безопасность  |   Веб – разработка
Публикации RSS  |  Комментарии RSS
https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js