Многие из нас работают в компаниях с уже устоявшимися процессами разработки прикладного ПО, и неотъемлемой частью этих процессов являются самые разнообразные документы. Однако, есть компании, в которых нет традиций и процессов написания технической документации, а вся информация находится у людей в головах и в корпоративной электронной почте. Если вы приходите из компании первого типа в компанию второго типа, вы очень быстро обнаруживаете, что рабочая документация нужна как воздух. Почему? Давайте рассмотрим основные типы рабочей документации в разработке ПО, и попытаемся представить себе жизнь без них.
Читать полностью »
Рубрика «документация» - 12
Про важность документирования
2014-04-03 в 8:14, admin, рубрики: документация, Программирование, процесс разработки, разработка, тестирование, метки: документация, процесс разработкиJSDuck — генератор документации
2014-03-04 в 9:43, admin, рубрики: javascript, Библиотека ExtJS/Sencha, документация, метки: документация Документирование является неотъемлемой частью хорошего кода и проекта в целом. Хорошие разработчики тратят много времени на поддержку документации, но в дальнейшем это окупается с лихвой: экономит время на поддержке кода, его расширении и исправлении багов, позволяет сократить время на погружение в проект новых разработчиков и т.д. Так же, хорошо документированный код неявно стимулирует разработчика к применению стандартов кодирования.
Читать полностью »
DevDocs: вся документация разработчика в одном месте, с быстрым и удобным интерфейсом
2014-02-04 в 19:14, admin, рубрики: Веб-разработка, документация, разработка, справочники, метки: документация, справочники 
Сайт devdocs.io — проект французского программиста Тибо Курубля. Здесь собрана и упорядочена документация по наиболее популярным веб-технологиям, фреймворкам и API, и многим другим средствам разработки. DOM, HTML, JavaScript, jQuery, Node.js, PHP, Ruby, Python, Git, Angular, Backbone, CoffeScript, Less, Sass, Redis и много чего ещё… Всё оформлено в едином стиле, по всей базе документации работает поиск, в том числе нечёткий. Есть возможность выбрать только необходимые технологии, по которым надо искать. Вообще, интерфейс DevDocs радует — ничего лишнего, всё очень понятно и функционально, доступно множество клавиатурных сокращений.
Читать полностью »
Github + Markdown = Viewdocs
2013-12-30 в 10:58, admin, рубрики: github, markdown, open source, Веб-разработка, документацияДля ПО с открытым исходным кодом очень большое значение имеет документация. На своем опыте я убедился, что написание хорошей документации зачастую даже важнее написания тестов.
Когда я перерос README на Github, я рассматривал только 2 варианта для документации: Github Pages и Read the Docs. К сожалению, у меня возникли проблемы с обоими. Главным образом, Read the Docs заставляет меня использовать reStructured Text, а Github Pages подразумевает поддержку отдельной ветки и использование генератора статичных страниц.
Читать полностью »
Детальное описание действий IT-отдела — базовый набор документации
2013-07-19 в 10:56, admin, рубрики: аутсорсинг, Блог компании КРОК, глоссарий, документация, каталог, системное администрирование, стандарт, техподдержка, управление проектами, метки: аутсорсинг, глоссарий, документация, ит-аутсорсинг, каталог, стандарт, техподдержкаВо многих западных странах IT-аутсорсинг регулируется либо отраслевыми стандартами, либо вообще на госуровне. У нас такого нет. Поэтому за несколько лет был собран документ, который детально определяет термины в IT-аутсорсинге и расписывает, что в какой тип работ конкретно входит. С его помощью мы документируем работы, а потом чётко и прозрачно считаем, что сколько стоит.
Вот глоссарий терминов, а вот каталог IT-услуг. Эти документы можно свободно скачивать и использовать. Особенно рекомендую это руководителям IT-подразделений.
Ниже я расскажу, зачем мы всё это сделали, и для каких случаев документ будет очень полезен.Читать полностью »
Применение JSON-Schema в тестировании и документировании API
2013-07-16 в 6:15, admin, рубрики: javascript, json, json-schema, XML, Блог компании 2ГИС, документация, разработка, метки: javascript, json, json-schema, XML, документация Справочный API 2ГИС разрабатывается уже 4 года. Появилось около 40 методов, которые возвращают достаточно крупные и иерархически сложные структуры в формате JSON и XML. Совсем недавно я решил поделиться накопленным опытом и выступить на конференции DevConf.
Одна из тем доклада вызвала наибольший интерес у участников — это использование JSON-Schema при тестировании формата выдачи API. В этой статье я расскажу, какие задачи решает этот подход, какие имеет ограничения, что вы получаете из коробки, а что идёт бонусом. Поехали!
Документация MySQL уведена от лицензии GPL
2013-06-18 в 22:16, admin, рубрики: GPL, mariadb, mysql, open source, документация, копирайт, свободная лицензия, метки: GPL, mariadb, mysql, документация, свободная лицензияРазработчики MariaDB случайно заметили, что в промежутке от MySQL 5.5.30 к MySQL 5.5.31 в проекте изменился текст лицензии во всех файлах в каталоге man/.
Вместо прежнего краткого текста «Эта документация является свободным программным обеспечением, вы можете распространять и/или изменять её только под условиями лицензии GNU General Public License, как опубликовано Фондом свободного ПО; версия 2 лицензии» теперь длинное описание, начинающееся со слов: «Это программное обеспечение и сопутствующая документация распространяются под лицензионным соглашением, которое содержит ограничения на использование и разглашение и защищена законами об интеллектуальной собственности».
Читать полностью »
Как я перестал волноваться и стал отдавать метаданные restful API
2013-03-28 в 10:13, admin, рубрики: api, asp.net webapi, MetaData, rest, Блог компании «Дневник.ру», документация, метки: api, asp.net webapi, MetaData, rest, документация 
Если вы делаете публичный API, то скорее всего сталкивались с проблемой его документации. Большие компании делают специальные порталы для разработчиков, где можно почитать и обсудить документацию, или скачать библиотеку-клиент для вашего любимого языка программирования.
Поддержка такого ресурса (особенно в условиях, когда API активно развивается) — достаточно трудозатратное дело. При изменениях, приходится синхронизировать документацию с фактической реализацией и это напрягает. Синхронизация состоит из:
- Проверки, что вся существующая функциональность описана в документации
- Проверки, что всё описанное работает как заявлено в документации
«ВКонтакте» обновил документацию API
2013-03-22 в 15:16, admin, рубрики: vk api, Веб-разработка, Вконтакте, Вконтакте API, документация, метки: vk api, Вконтакте, документация 
Вчера социальная сеть ВКонтакте обновила документацию для разработчиков и запустила баг-трекер.
Под катом обзор новых возможностей документации.Читать полностью »
Перевод сайта разработчиков Android на русский
2013-01-31 в 10:58, admin, рубрики: android, Google, документация, Разработка под android, метки: android, Google, документация Как известно, у Android есть официальный сайт разработчиков. Не так давно он претерпел полный редизайн.
Читать полностью »