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

Документируем код эффективно при помощи 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, и сделал это понимая, что и почему я делаю, без шаманства с чужими рецептами.

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

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

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

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

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

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

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

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

Mojolicious — восхитительный современный веб-фреймворк для Perl. Из недостатков я могу назвать только два: политика в отношении обратной совместимости и документация.

Содержание

  1. Недостатки
  2. Роутинг: внутреннее устройство
  3. Роутинг: настройка
  4. Параметры HTTP-запроса
  5. Парсинг
  6. Tips & Tricks
    1. Поддержка неблокирующих приложений в режиме CGI
    2. Как работает Mojo::UserAgent при тестировании своего приложения
    3. ojo и Mojolicious::Lite
    4. Переменные окружения

Недостатки

В официальном FAQ написано: "… we will always deprecate a feature before removing or changing it in incompatible ways between major releases … as long as you are not using anything marked experimental, untested or undocumented, you can always count on backwards compatibility …". Для начала, вторая фраза противоречит первой. Далее, вот цитата из Guides::Contributing «Features may only be changed in a major release or after being deprecated for at least 3 months.». Честно говоря, 3 месяца это и так смешной срок когда речь идёт об обратной совместимости, но похоже что даже этот срок соблюдается не всегда (поддержку «X-Forwarded-HTTPS» сделали deprecated два месяца назад, а удалили месяц назад — да, это был «major release» поэтому формально правила не нарушены, но общее отношение к обратной совместимости вполне показательно). Как много разработчиков обновляет фреймворк чаще чем раз в 3 месяца, да ещё и при этом тщательно вычитывает Changes или логи своего приложения на предмет deprecated-предупреждений? При этом, в течении последнего года было deprecated примерно 20 функций/фич. На практике, конечно, всё не так плохо, как это звучит — что-то ломается не так уж часто (лично меня за последний год коснулась только замена $app->secret() на $app->secrets()). Но факт остаётся фактом — обратную совместимость ломают, ломают часто, причём без по-настоящему веских причин: например, в случае с secret() абсолютно ничего не мешало добавить в код

sub secret { shift->secrets([shift]) }

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

Что касается документации, то многие считают её отличной, даже одним из серьёзных достоинств Mojolicious, но никак не недостатком. Проблема с документацией в том, что она вся сосредоточена на примерах. Это реально круто, когда ты начинаешь изучать фреймворк. Это экономит кучу времени, когда тебе нужно сделать фичу и ты быстро гуглишь пример аналогичной фичи в официальных guides. Но как только ты выходишь за рамки стандартных задач и возникает необходимость понять, как что-то устроено идеологически или архитектурно, какие конкретно параметры может принимать эта функция и что конкретно она может возвращать в разных ситуациях — выясняется, что для многих модулей Mojolicious такая документация отсутствует в принципе. И не потому, что эта информация относится к «недокументированным возможностям» — почти всё это мельком упоминается здесь и там в разных примерах, а значит считается «документированным». Нередко есть несколько способов получить доступ к определённым данным (параметры запроса, тело ответа, etc.) но не описано чем они друг от друга отличаются и в каких ситуациях правильнее пользоваться какими способами. И последнее — алфавитный порядок функций в доке, серьёзно?! Нет, я понимаю, все люди разные и кому-то наверняка это удобно, но многим всё-таки на порядок проще воспринимать документацию в которой функции сгруппированы по задачам. (Хотя в коде, особенно при чтении его через браузер, где не так удобно пользоваться поиском как в Vim, алфавитный порядок функций неожиданно оказался довольно удобным — кроме new/DESTROY/AUTOLOAD — их всё-таки лучше размещать в начале.) В результате, чтобы разобраться приходится вычитывать код (некоторые предпочитают вместо этого смотреть тесты!), что не так просто — во-первых он не является эталоном читабельности: автор любит использовать фишки перла, которые позволяют писать код компактно (и нередко такой код быстрее работает), но читабельность это ухудшает; во-вторых активное использование и наследования и обмена событиями между объектами усложняет понимание того, что и как происходит внутри 104 классов, из которых состоит Mojolicious-5.

С проблемой обратной совместимости мы мало что можем сделать (хотя, наверное, можно сделать плагин к Mojolicious, который будет её эмулировать по мере возможности). Зато вторую проблему решить не сложно — недостающую документацию можно написать самостоятельно. По мере изучения Mojolicious я планирую описывать некоторые вещи, которые, по-хорошему, должны быть в официальной документации, отсюда и название этой статьи.
Читать полностью »

Перевод документации по Unity3D
Доброго времени суток.
Многие уже знаю, что сайт unity3d.com стал доступен на русском языке.
О русификации сайта было объявленно на DevGAMM. Тогда же Unity-пользователи высказывали негодование, что документация до сих пор только на английском.
На самом деле документация переводилась, но маленькой группой переводчиков.
Но с выходом Unity 4.5 доступ к переводу был открыт! И теперь любой пользователь Unity может переводить документацию!
Ссылка для желающих переводить: http://translate.unity3d.com

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

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


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