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

Всем наверно известен замечательный OpenSource проект Trac, позволяющий организовать рабочий процессы при разработке программного обеспечения. Однако его развертывание и настройка является не простой задачей. Информация в интернете разрозненная и часто уже устаревшая. В этом я смог сам убедиться настраивая Trac интегрированный с Gitolite на связке Nginx+UWSGI.

После небольшой увертюры с бубном у меня родился этот документ являющийся практически пошаговой инструкцией по развертыванию проекта Trac. Надеюсь это пригодится кому-нибудь еще.
Читать полностью »

Взгляд на функциональные требования к интеграционной системе

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

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

Как это было

Не так давно сталкнулся с одной проблемой, возникшей при переезде на php 5.4. Задача состояла в тестировании функционала, который использовал родные функции. К слову, Fumocker отлично справляется с этой задачей, позволяя в тестах переопределять встроенные функции. Я написал пачку тестов и запустил их локально. Все тесты прошли успешно. Отлично! Задача была сделана и я был в полном счастье, пока не добавил проект в travis-ci. И? Сборка была сломана под php 5.4, когда под 5.3 всё светилось зелёным.

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

Я веду курс веб-программирования. Когда учишь людей, поговорка «сапожник без сапог» к тебе относиться не должна: ты должен делать всё без видимых усилий и быстро. Учебник должен делаться легко и просто, и выглядеть хорошо.

В общем, если вам нужно сделать документацию, учебник или просто набор текстов с иллюстрациями, то вам нужен Python Sphinx, и здесь я расскажу, как быстро его настроить и использовать.

Пустая страница новой документации
Читать полностью »

Система online документации для JavaScript — ADWiki

Ссылочки

Что ADWiki умеет:

  • Парсить файлы Вашего проекта описанные на jsdoc
  • Поднимать сайт с чистеньким дизайном на bootstrap
  • Организовывать на сайте небольшой блог, где Вы сможете дополнять документацию статьями о проекте

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

Многие пользователи Хабра являются либо приобретателями авторских прав на программное обеспечение либо продавцами таких прав.

В своей первой статьей на Хабре я хотел бы совсем вкратце поделиться своими соображениями относительно приобретения и надлежащего оформления авторских прав на программное обеспечение в условиях действующего законодательства Российской Федерации.

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

Пост написан из-за появления вчерашних новостей о вирусе-шпионе (например, вот). как ни странно, но проблема защиты промышленных объектов в РФ ставится не так остро, как должна бы… в СМИ очень часто можно услышать про законы о персональных данных, а вот защитой АСУ ТП(системы управления технологическими процессами), похоже, никто особо не занимался (защита критически важных объектов регламентирована документами ФСТЭК, но они имеют гриф и не доступны простым смертным). Для тех же компаний, которые не попали в список этих самых «критически важных», существует только стандарт Газпрома… и все, больше никаких документов и рекомендаций в области защиты АСУ ТП нет.
В США дело обстоит в корне наоборот, и американский US CERT выкладывает в свободный доступ свои рекомендации по АСУТП. Желающих ознакомиться прошу под кат.Читать полностью »

Уровень: начинающим, продолжающим, ленивым

Что, опять? Но зачем!?

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

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

Мотивация

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

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

Во всяком случае, это только первый черновик стандарта, который я предлагаю. Комментарии приветствуются!

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

В справочнике jquery.page2page.ru появилась документация jQuery UI. Помимо подробного описания каждого плагина, она содержит статьи о фабрике виджетов, с помощью которой можно создавать собственные подобные плагины, правилах темизации (оформления) виджетов UI, собственной системе позиционирования UI, а так же о расширенных анимационных эффектах, доступных при подключении jQuery UI к сайту. Ну и конечно же есть вводная статья с которой можно начать изучение jQuery UI.

Кроме этого, обновлена карта функций, вЧитать полностью »