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

Недостаточно просто закодировать и протестировать программу.

Бывало у Вас так, что после запуска программы уходит сотрудник, который с ней работал долгое время? Или возникает необходимость доработать программу, но никто уже не помнит как она устроена?

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

Согласитесь, такие ситуации происходят с завидной периодичностью и встречаются сплошь и рядом.

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

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

Однако есть один момент, на который мало кто обращает внимание.

Давайте рассмотрим его на конкретном примере...Читать полностью »

Жизненный цикл документа в профессиональной справочной системе. Немного сказочный пост о том, как кипа бумаги превращается в систему. Часть 2 - 1
Добрый день, друзья!

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

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

Построение диаграмм и графов в Doxygen - 1

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

Документируем код эффективно при помощи Doxygen - 1

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

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

Разметка структурированных данных позволяет показывать дополнительную информацию с вашего сайта в результатах поиска и сервисах Google. Мы рады представить несколько обновлений, которые помогут создавать разметку на сайте:

Инструмент проверки структурированных данных

Новый Инструмент проверки структурированных данных лучше показывает то, как Google интерпретирует разметку структурированных данных на странице сайта.
Инструмент проверки структурированных данных
Читать полностью »

Вы пишите лишнюю документацию для вашего проекта? Нет? Тогда вам ее недостаточно!

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

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

Sandcastle и SHFB Это статья-заметка о работе с Sandcastle и SHFB, дабы не забыть самому и рассказать другим.

Со времён последней статьи о Sandcastle («Создание документации в .NET») прошло 4 года, так что пора освежить некоторые моменты этой утилиты документации.
Читать полностью »

Об установке и базовой настройке rtorrent на хабре хватает статей, как и споров о том, стоит ли вообще связываться с хардкорным rtorrent или лучше обойтись чем-нибудь более дружественным к пользователю. Лично я много лет назад пересмотрел все качалки и в результате rtorrent оказался самым стабильным и эффективным. Интерфейс у него не самый удобный, но достаточно понятный и юзабельный чтобы это не стало серьёзной проблемой. Альтернативные интерфейсы вроде rutorrent у меня как-то не прижились - ставить php только ради rutorrent неохота, а остальные варианты выглядят совсем слабо (и ни одного кроме rutorrent даже нет в портаж Gentoo).

 Разбираемся с rtorrent всерьёз 

Одно из основных преимуществ rtorrent — очень гибкие возможности по его настройке и автоматизации. К сожалению, синтаксис ~/.rtorrent.rc достаточно нестандартный, нормальная документация отсутствует, поэтому обычно настройка сводится к поиску и копированию (попытка что-то в них изменить кроме констант/путей к каталогам обычно проваливается) готовых рецептов или вообще ограничивается редактированием констант в базовой конфигурации.

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

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

И начать делать полезную документацию

Как перестать делать исполнительную проектную документацию

Подавляющее большинство проектов по построению ИТ-инфраструктуры, реализованных даже очень крупными системными интеграторами, обладает одним существенным недостатком – бесполезной проектной документацией. Нет, нет, конечно же, документация содержит все необходимые данные и, прочитав ее можно разобраться, что и как было организовано. Бесполезность ее проявляется при дальнейшей эксплуатации информационных систем и выражается в сложности поддержания документации в актуальном состоянии и невозможности оперативно найти в ней нужную информацию. Как следствие, данная проектная документация, со временем, вместо полезного справочного материала становится еще одним красивым и бесполезным отчетным документом.

В данной статье я бы хотел поделиться с моими коллегами некоторыми принципами составления проектной документации, которые мы используем в своей работе и которые, возможно, позволят вашим клиентам наслаждаться не только качественно построенной вами ИТ-инфраструктурой, но и легко и непринуждённо поддерживать в актуальном виде документацию по ней, годами вспоминая вас добрым словом. Приступим:Читать полностью »

Доброго времени суток, уважаемые!
Давно не писал на Хабр, не было времени, много работы было. Но теперь разгрузился и сформировались мысли для нового поста.

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

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


https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js