Рубрика «документирование»

Привет! У нас прошла конференция по разработке технической документации – ProКонтент 2019. Мне довелось изнутри посмотреть на процесс рождения конференции и даже выступить с пятиминутным мини-докладом. Не претендуя на объективность, очень кратко расскажу про доклады, которые мне больше всего понравились.
Читать полностью »

Писал комментарий к статье и понял, что надо выносить в отдельный пост.
Как многие отмечают там в комментариях статья отстой, человек не разбирается и смешал всё в кучу, попробую поделиться своими выводами от использования разных разметок.
Читать полностью »

Log in или Log on? Front-end или Frontend? Продолжаем разбираться - 1

В прошлый раз мы говорили о разнице между login и log in. В продолжение темы — ещё несколько нюансов, о которых вы просили рассказать в комментариях.

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

Login или Log in? - 1

‘Login’ или ‘log in’? Одно слово или два? Это достаточно распространенный вопрос среди тех, кто пишет на английском языке. Давайте разберемся, как же правильно.

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

RAML 1.0

О RAML — языке разметки, используемом для описания RESTful API, мы уже писали. В обсуждении статьи на Хабрахабре один из читателей заметил, что RAML уже давно не обновляется, чуть ли не с лета 2014 года.

Несколько месяцев формат RAML был существенно усовершенствован. Новая спецификация версии 1.0 была опубликована на официальном сайте относительно недавно, в начале октября 2015 года. По сравнению с предыдущей версией (0.8) в неё было внесено много изменений и дополнений. О наиболее значительных нововведениях мы подробно расскажем в этой статье.
Читать полностью »

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

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

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

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

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

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

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

Оформление документации в Doxygen - 1

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

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

Quick Help научился брать документацию из комментариев:

Quick Help для своего кода в XCode 5
Читать полностью »

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

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

Вот те, кому надоело видеть/выковыривать из текста лишние пробелы, кому необходимо обеспечить совместную разработку документа с хранением в git/svn и много другого полезного — могут нажать кнопку ниже, чтобы прочитать немного больше про замечательный редактор Lyx.
Читать полностью »

Преамбула

Всем знакома ситуация, когда на весь зоопарк из компьютеров, ноутбуков, планшетов, копировальной техники, серверов, активного сетевого оборудования и т.д. всего один админ. Он альтруист, вы не подумайте. Он любит свою работу. Он разбирается в теме. Он эффективен и глаза горят. Но как ни крути, когда вся ИТ функция предприятия, пусть даже небольшого, завязана на одного человека – это такой нехилый эксплуатационный риск. Я всегда задаю вопрос: «Что будет, если он, например, заболеет или уволится одним днем без объяснения причин?» Сколько дней вы продержитесь, пока найдете человека, который будет разбираться во всем этом зоопарке с нуля? Нет, ну серьезно? Представьте, что завтра этого человека не будет, а вас закончились лицензии, интернет, бумага в принтере и умер сервер с базой данных клиентов.
Читать полностью »