Успешный программный продукт обычно проходит за свою жизнь через руки множества разработчиков. Вы — лишь одно из звеньев в цепочке опекунов вашего проекта, и каждая строчка кода, которую Вы написали — это оставленный Вами артефакт, который когда-нибудь будет изучаться Будущим Разработчиком. Также, как Вы унаследовали решения разработчиков, которые были до Вас, другие разработчики унаследуют решения, которые Вы делаете сегодня. Они получат от нас в наследство все наши недоразумения, срезанные нами углы, примененные нами недопонятые паттерны и техники, наше невнимание к деталям, нашу лень, наши изменения, сделанные на скорую руку, наших скелетов в шкафах, наше грязное белье. И гораздо реже — выгоду от нашей дисциплинированности, наших обсуждений и подготовок.
Рубрика «документация» - 11
Работая в интересах Будущих Разработчиков
2012-11-20 в 15:09, admin, рубрики: cooperations, rails, ruby on rails, документация, командная работа, культура кода, паттерны, проектирование, Проектирование и рефакторинг, рефакторинг, Совершенный кодTrac и его друзья Gitolite, Nginx и UWSGI
2012-11-18 в 13:59, admin, рубрики: gitolite, nginx, trac, uwsgi, документация, инструкция по установке, Программирование, разработка, управление проектами, метки: gitolite, nginx, trac, uwsgi, документация, инструкция по установкеВсем наверно известен замечательный OpenSource проект Trac, позволяющий организовать рабочий процессы при разработке программного обеспечения. Однако его развертывание и настройка является не простой задачей. Информация в интернете разрозненная и часто уже устаревшая. В этом я смог сам убедиться настраивая Trac интегрированный с Gitolite на связке Nginx+UWSGI.
После небольшой увертюры с бубном у меня родился этот документ являющийся практически пошаговой инструкцией по развертыванию проекта Trac. Надеюсь это пригодится кому-нибудь еще.
Читать полностью »
Вопросы «Что? Где? Когда?» в функциональных требованиях
2012-11-17 в 21:54, admin, рубрики: Анализ и проектирование систем, аналитика, документация, интеграция, разработка, метки: аналитика, документация, интеграцияВзгляд на функциональные требования к интеграционной системе
Наверное, всем разработчикам приходилось сталкиваться как с замечательными, так и с отвратительными требованиями к системе. В каждой отрасли своя специфика и определить универсальные стандарты можно только на бумаге. А когда по этим стандартами пишутся реальные требования, мы получаем стостраничные документы «ни-о-чем», которые в лучшем случае не мешают разработке, а зачастую – вводят в заблуждение относительно реальных потребностей пользователя и заказчика.
Поэтому, в этом посте я постараюсь кратко выразить свою мысль относительно определения требований именно к интеграционным системам. Прошу в ином контексте идею не рассматривать, иначе пост покажется бредом, а я – идиотом.
Читать полностью »
Недокументированные изменения или PHP 5.4 и перегрузка функций
2012-10-05 в 5:55, admin, рубрики: php, php 5.4, документация, недокументированные возможности, метки: php 5.4, документация, недокументированные возможностиКак это было
Не так давно сталкнулся с одной проблемой, возникшей при переезде на php 5.4. Задача состояла в тестировании функционала, который использовал родные функции. К слову, Fumocker отлично справляется с этой задачей, позволяя в тестах переопределять встроенные функции. Я написал пачку тестов и запустил их локально. Все тесты прошли успешно. Отлично! Задача была сделана и я был в полном счастье, пока не добавил проект в travis-ci. И? Сборка была сломана под php 5.4, когда под 5.3 всё светилось зелёным.
Именно этот факт навел меня на мысль, что между 5.3 и 5.4 должна быть разница в перегрузке функций.
Читать полностью »
Делаем учебник или документацию за час на Сфинксе
2012-10-02 в 20:31, admin, рубрики: python, документация, разработка, учебник, Учебный процесс в IT, метки: python, документация, учебникЯ веду курс веб-программирования. Когда учишь людей, поговорка «сапожник без сапог» к тебе относиться не должна: ты должен делать всё без видимых усилий и быстро. Учебник должен делаться легко и просто, и выглядеть хорошо.
В общем, если вам нужно сделать документацию, учебник или просто набор текстов с иллюстрациями, то вам нужен Python Sphinx, и здесь я расскажу, как быстро его настроить и использовать.
Система online документации для JavaScript — ADWiki
2012-09-28 в 11:33, admin, рубрики: autodafe, docs, javascript, node.js, документация, метки: autodafe, docs, javascript, node.js, документация
Ссылочки
- Живая демонстрация
- Код задокументированного файла из демки
- Да и вобще весь сайт autodafe.ws полностью работает на ADWiki
- Инструкция по установке ADWiki
- Проект на GitHub
Что ADWiki умеет:
- Парсить файлы Вашего проекта описанные на jsdoc
- Поднимать сайт с чистеньким дизайном на bootstrap
- Организовывать на сайте небольшой блог, где Вы сможете дополнять документацию статьями о проекте
Приобретение и надлежащее оформление прав использования программного обеспечения
2012-06-27 в 11:33, admin, рубрики: договор, документация, копирайт, право, Программирование, Программное обеспечение, Софт, метки: договор, документация, право, программное обеспечениеМногие пользователи Хабра являются либо приобретателями авторских прав на программное обеспечение либо продавцами таких прав.
В своей первой статьей на Хабре я хотел бы совсем вкратце поделиться своими соображениями относительно приобретения и надлежащего оформления авторских прав на программное обеспечение в условиях действующего законодательства Российской Федерации.
Побудило к написанию настоящей статьи моя ежедневная практика и фактически непонимание окружающих, в том числе специалистов казалось бы, очевидных вещей при оформлении договоров по приобретению прав на использование программного обеспечения.
Читать полностью »
Защита АСУ ТП по-американски
2012-05-30 в 2:58, admin, рубрики: асу тп, будущее здесь, документация, информационная безопасность, стандарты, метки: асу тп, документация, информационная безопасность, стандарты Пост написан из-за появления вчерашних новостей о вирусе-шпионе (например, вот). как ни странно, но проблема защиты промышленных объектов в РФ ставится не так остро, как должна бы… в СМИ очень часто можно услышать про законы о персональных данных, а вот защитой АСУ ТП(системы управления технологическими процессами), похоже, никто особо не занимался (защита критически важных объектов регламентирована документами ФСТЭК, но они имеют гриф и не доступны простым смертным). Для тех же компаний, которые не попали в список этих самых «критически важных», существует только стандарт Газпрома… и все, больше никаких документов и рекомендаций в области защиты АСУ ТП нет.
В США дело обстоит в корне наоборот, и американский US CERT выкладывает в свободный доступ свои рекомендации по АСУТП. Желающих ознакомиться прошу под кат.Читать полностью »
Еще раз о документации
2012-05-16 в 7:09, admin, рубрики: администрирование, документация, документирование, сервера, Серверное администрирование, системное администрирование, метки: администрирование, документация, документирование, сервераУровень: начинающим, продолжающим, ленивым
Что, опять? Но зачем!?
О документации сказано уже много, в том числе и на хабре, где я нашел несколько статей. Однако те статьи которые я смотрел (раз, два, три, четыре) отвечают на вопросы зачем и что нужно документировать. Я же хочу привести два простых примера показывающих как, а также демонстрирующих, что документация может быть мягкой и шелковистой легкой и приятной.
Читать полностью »
Стандарт open source документации
2012-04-17 в 8:59, admin, рубрики: gtd, open source, документация, переводыХотя эта идея на первый взгляд может показаться глупой, упрощенной и слишком общей, я хотел бы предложить стандартый способ документирования проектов с открытым исходным кодом. Я знаю, что каждый проект индивидуален и моя идея уже вызвала у вас улыбку, но я надеюсь вы поймёте меня, если прочитаете этот небольшой пост.
Мотивация
Нас, авторов кода, стандарт спасёт от необходимости придумывать структуру документации для очередного проекта. Намного проще заполнять пробелы в заранее подготовленной структуре, чем думать о ней каждый раз. А чем проще и быстрее это будет происходить — тем больше разработчиков будет создавать хорошую документацию. (В конце концов, у нас останется больше времени на код и архитектуру — прим. пер.)
Стандартный формат также может сделать документацию более простой для понимания, если читатель будет знаком с её структурой. Для большинства вещей дизайн является лучшим способом привлечь потребителя, и именно дизайн ему нужен. Так что желание удовлетворить всех часто приводит к тому, что никто не оказывается удовлетворён, это касается и документации. Несмотря на то, что для обучения стоит применять персональный подход, я считаю, что тщательно продуманная и организованная документация позволит охватить больший процент потенциальных пользователей. Попытка же удовлетворить желания всех приводит к чрезмерному документированию: подобную документацию трудно сопровождать и она отпугивает читателя.
Во всяком случае, это только первый черновик стандарта, который я предлагаю. Комментарии приветствуются!