Pull to refresh

Protonote: документирование разработки липкими бумажками

Lumber room

Мне нравятся простые вещи. Мне нравится обдумать предстоящую работу над проектом, и затем сделать её. Во время процесса мышления создаются разнообразные записи. Элегантный инструмент создал Майк Падилла (Mike Padilla) — Protonotes, сервис для создания небольших заметок прямо в окне веб-сайта. Заметки выглядят точь-в-точь, как разбросанные по вашему рабочему столу липкие бумажки.

Задачу документирования разработки можно решить и с помощью Вики, электронной почты или систем управления проектами. Но по наглядности и метафоре — липкие бумажки на экране, — это что-то особенное.

После добавления кода загрузки Protonotes на свою страницу, все посетители этой страницы смогут добавлять, удалять и редактировать заметки без каких либо дополнительных телодвижений. Использование Protonotes очень удобно для заказчиков. Они получают возможность оставлять свои комментарии находясь на разрабатываемом сайте. Для администрирования заметок можно подключить их к своей базе данных (MySQL).

Кросс-пост с Стартаперы.ру — Инструменты бедуина
Total votes 9: ↑6 and ↓3 +3
Views 569
Comments 5

PHPDocumentor объединился с Docblox

PHP *
Несколько ранее я уже писал о появлении нового PHP-движка для автоматической генерации документации Docblox (тут и тут). Сегодня я с удивлением обнаружил, что теперь все нововведения из Docblox перекочевывают в PHPDocumentor. Предыдущая ветка PHPDocumentor 1.х теперь считается устаревшей, а основные нововведения будут появляться в ветке 2.х. Также обновлен официальный сайт phpDocumentor.
Читать дальше →
Total votes 21: ↑21 and ↓0 +21
Views 2.2K
Comments 5

Еще раз о документации

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

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


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



Да ну?
Total votes 20: ↑17 and ↓3 +14
Views 17K
Comments 33

WebAPI: автогенерация веб-документации REST API

Microsoft corporate blog Website development *.NET *
Translation
В этой записи блога мы близко рассмотрим ApiExplorer, являющийся реализацией IApiExplorer по умолчанию и увидим как с помощью него можно быстро сгенерировать веб-документацию по доступному REST API. В этой документации будет содержаться разнообразная информация, например, правильные URL, допустимые HTTP-методы, ожидаемые для запросов параметры. Такого рода информация для вашего REST-сервиса позволит сторонним разработчикам, потребляющим ваш API, точно знать как правильно вызывать его части. Наверное, самое приятное в такой странице веб-документации состоит в том, что она будет обновляться автоматически вместе с обновлением вашего REST API.

ApiExplorer


Основной целью этого класса является генерирование коллекции элементов ApiDescription. Это производится с помощью статической проверки маршрутов и доступных действий внутри ваших контроллеров. Каждый элемент ApiDescription описывает API доступный через ваш сервис. Как вы можете видеть на упрощенной диаграмме (рисунок 1) ApiDescription содержит базовую информацию такую как, HttpMethod, RelativePath, Documentation и т.д. Но кроме того, он содержит элемент ApiDescriptor, который является частью ядра WebAPI знающей все о соответствующем действии. Вы можете использовать этот элемент для получения доступа к обширной информации, такой как имя действия, возвращаемый тип, пользовательские атрибуты и т.д. Точно так же вы можете использовать элемент ParameterDescriptor для изучения ожидаемых параметров данного API.
Читать дальше →
Total votes 17: ↑13 and ↓4 +9
Views 18K
Comments 0

Годное ТЗ, очень коротко

Website development *
Recovery mode
Частенько, по долгу службы в том числе, приходится писать всякие ТЗ, а так же вникать и (командовать) создавать документацию по продуктам и решениям. ТЗ — для отношений с клиентом, документация — для разработчиков. Основные принципы, которые должны быть, коротко, под катом.
Читать дальше →
Total votes 35: ↑19 and ↓16 +3
Views 3.4K
Comments 5

О комментариях в коде замолвите слово

Programming *
Появился пост, в комментариях к которому (какая ирония) было много мнений,
что самый лучший код — self-documenting и все такое.

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

Читать дальше →
Total votes 47: ↑32 and ↓15 +17
Views 16K
Comments 23

Эксплуатационные риски и их минимизация

System administration *
Sandbox

Преамбула


Всем знакома ситуация, когда на весь зоопарк из компьютеров, ноутбуков, планшетов, копировальной техники, серверов, активного сетевого оборудования и т.д. всего один админ. Он альтруист, вы не подумайте. Он любит свою работу. Он разбирается в теме. Он эффективен и глаза горят. Но как ни крути, когда вся ИТ функция предприятия, пусть даже небольшого, завязана на одного человека – это такой нехилый эксплуатационный риск. Я всегда задаю вопрос: «Что будет, если он, например, заболеет или уволится одним днем без объяснения причин?» Сколько дней вы продержитесь, пока найдете человека, который будет разбираться во всем этом зоопарке с нуля? Нет, ну серьезно? Представьте, что завтра этого человека не будет, а вас закончились лицензии, интернет, бумага в принтере и умер сервер с базой данных клиентов.
Читать дальше →
Total votes 12: ↑8 and ↓4 +4
Views 8K
Comments 2

Скажем нет форматированию пробелами и энтерами

LaTeX *
Sandbox
Знакомство каждого человека с компьютером рано или поздно подходит к редактированию документов.
А вот дальше, как говорится, есть варианты.


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

Вот те, кому надоело видеть/выковыривать из текста лишние пробелы, кому необходимо обеспечить совместную разработку документа с хранением в git/svn и много другого полезного — могут нажать кнопку ниже, чтобы прочитать немного больше про замечательный редактор Lyx.
Want to know more
Total votes 78: ↑65 and ↓13 +52
Views 33K
Comments 80

Документирование в разработке ПО

System Analysis and Design *
Sandbox

INTRO


Добрый день, уважаемое сообщество.
Позвольте представиться. Я бизнес-аналитик, уже десять лет работаю в области разработки заказного программного обеспечения, в последнее время совмещаю роли аналитика и руководителя проектов.

Одним из болезненных вопросов в разработке ПО всегда был и остаётся процесс документирования этой самой разработки. Вам доводилось приходить на проект, который делают уже пару лет, но, при этом, вы никак не можете с ним разобраться, потому что из документов есть одно техническое задание, да и то написано в самом начале и не отражает и половины функционала системы? Мне доводилось. И это, честно говоря, очень печальное и байтораздирающее зрелище.
Поэтому на всех своих проектах я стараюсь изначально построить процесс так, чтобы неопознанного и неописанного функционала не было, все члены команды вовремя получали актуальную информацию и вообще был мир во всём

Итак, для начала отвечу на главный вопрос: для чего всё это нужно.
Есть несколько причин.
Читать дальше →
Total votes 26: ↑26 and ↓0 +26
Views 132K
Comments 42

Документирование — отдельная статья доходов проекта

Website development *System Analysis and Design *
Sandbox

Введение


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

Оно суть головная боль и корм для корпоративной жабы компании-разработчика. С точки зрения «типового интегратора», это некий побочный процесс, результаты которого в основном нужны для закрытия официальных требований контрактов. Не будь требований – сколько можно было бы высвободить ресурсов! Да еще и не отвлекать от работы истинных кормильцев компании: продавцов, менеджеров и в некоторой степени программистов. Картина комплектование и организации работы «мощностей» по разработке документации – отдельная грустная песня, не для этой статьи.

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

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

Уважаемые сейлы, менеджеры продуктов и проектов – давайте активнее продвигать документацию. Давайте на ней зарабатывать!
Читать дальше →
Total votes 12: ↑9 and ↓3 +6
Views 9.7K
Comments 14

Как взять под контроль Virtual Machine Sprawl: 7 полезных отчетов в Veeam Availability Suite

Veeam Software corporate blog System administration *Virtualization *Backup *
Tutorial
«Ты суслика видишь? Нет? А он есть!»

Аналогичная ситуация вполне возможна и с бесконтрольным ростом числа виртуальных машин (Virtual Machine Sprawl) — до определенного момента мы не считаем, что такая проблема имеет место быть в нашей инфраструктуре, а на самом деле она есть, просто не показывает себя в натуральную величину.

А в чем, собственно, дело?

Проблема бесконтрольного увеличения поголовья виртуальных машин довольно типична для быстро растущих виртуальных инфраструктур. Начинается всё с вполне резонного стремления того или иного подразделения компании работать со своими специализированными приложениями на выделенных серверах. Разумеется, благодаря виртуализации они получают такую возможность. А теперь, уважаемые читатели, сотрудники IT-отрасли, разработчики и тестировщики, прикиньте хотя бы приблизительно, сколько виртуальных машин вы засетапили, скажем, за последние полгода? А сколько из них было позабыто и позаброшено после успешного релиза?

Получается, что чем больше виртуализация проникает в рабочую среду и помогает решать производственные задачи, тем больше «виртуальных отходов» появляется в этой самой среде (как, впрочем, почти при любом производстве). Это-то и приводит к проблеме бесконтрольного роста количества виртуальных машин (VM sprawl).
Читать дальше →
Total votes 3: ↑2 and ↓1 +1
Views 2.9K
Comments 0

Оформление документации в Doxygen

Programming *C++ *C *C# *


Данная статья входит в получившийся цикл статей о системе документирования Doxygen:

  1. Документируем код эффективно при помощи Doxygen
  2. Оформление документации в Doxygen
  3. Построение диаграмм и графов в Doxygen

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

В данной статье я отвечу на этот вопрос. Для этого мы рассмотрим общие принципы оформления документации Doxygen, познакомимся с ними, и посмотрим на примерах, чего можно добиться, основываясь на них.
Читать дальше →
Total votes 32: ↑30 and ↓2 +28
Views 52K
Comments 1

Как написать диздок

VK corporate blog Website development *Game development *


Запрос «как написать диздок», заданный в любой поисковик, даёт немало ответов, представляющих собой как перевод западных статей, так и авторские размышления на эту тему из России, или даже дизайн проекта «Курочка Ряба». В воображении читателя предстает большой единый документ, описывающий идею и геймплей игры с перечислением всех ее фич. Возможно, читатель однажды приходит с такими идеями работать геймдизайнером в крупную российскую или западную компанию, на крупный проект… И обнаруживает, что таких документов больше не существует.
Читать дальше →
Total votes 47: ↑43 and ↓4 +39
Views 117K
Comments 11

От геймдизайна до геймплея

VK corporate blog Website development *Game development *
image

Итак, после долгих трудов и размышлений, чтения статей, может быть даже моей предыдущей, после анализа опыта конкурентов, общения с коллегами-геймдизайнерами за чашечкой кофе (или кружкой пива?), прототипов и итераций — дизайн-документ небольшой фичи или целой игры готов. Победа?! Как бы не так.

В этой статье речь пойдет о том тернистом пути, который проходит геймдизайн от документа до реализации в игре, причем как раз с позиции самого геймдизайнера. Как и в прошлой статье, не ставится задача детально показать весь процесс. Текст ориентирован на тех, кому интересен опыт работы геймдизайнера в крупной команде.
Читать дальше →
Total votes 30: ↑27 and ↓3 +24
Views 34K
Comments 7

Автоматизация оформления документации

Python *Data visualization *Technical Writing *
Работая над проектами связанными с авионикой мне потребовалось оформить несколько комплектов документации с полным описанием проекта. Также следовало учитывать требования многих ГОСТов на оформление и на содержание документации, таких как ЕСПД, КТ-178B и других.

Описание должно было в себя включать:
  • Планы разработки ПО
  • Требования к ПО
  • Описание реализации требований к ПО
  • Таблицы трассируемости(соответствия) требований к ПО и реализации
  • Описание тестов на ПО (Примеры и процедуры верификации ПО)
  • Таблицы трассируемости(соответствия) требований к ПО и тестов
  • Отчет об обнаруженных проблемах
  • Указатель конфигурации(описание версии ПО и совместимости со сторонним ПО и оборудованием)


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



Далее в статье я расскажу как я решил эту проблему.

Читать дальше →
Total votes 9: ↑8 and ↓1 +7
Views 21K
Comments 2

RAML 1.0: обзор нововведений

Selectel corporate blog API *
RAML 1.0

О RAML — языке разметки, используемом для описания RESTful API, мы уже писали. В обсуждении статьи на Хабрахабре один из читателей заметил, что RAML уже давно не обновляется, чуть ли не с лета 2014 года.

Несколько месяцев формат RAML был существенно усовершенствован. Новая спецификация версии 1.0 была опубликована на официальном сайте относительно недавно, в начале октября 2015 года. По сравнению с предыдущей версией (0.8) в неё было внесено много изменений и дополнений. О наиболее значительных нововведениях мы подробно расскажем в этой статье.
Читать дальше →
Total votes 24: ↑24 and ↓0 +24
Views 14K
Comments 15

Login или Log in?

Website development *Development of mobile applications *IT Standards *
Sandbox


‘Login’ или ‘log in’? Одно слово или два? Это достаточно распространенный вопрос среди тех, кто пишет на английском языке. Давайте разберемся, как же правильно.

Читать дальше →
Total votes 147: ↑134 and ↓13 +121
Views 77K
Comments 72

Log in или Log on? Front-end или Frontend? Продолжаем разбираться

Website development *Development of mobile applications *IT Standards *


В прошлый раз мы говорили о разнице между login и log in. В продолжение темы — ещё несколько нюансов, о которых вы просили рассказать в комментариях.

Читать дальше →
Total votes 61: ↑56 and ↓5 +51
Views 26K
Comments 33

Семантическая разметка: LaTeX, DocBook или ???

Open source *Semantics *XML *LaTeX *XSLT *
Писал комментарий к статье и понял, что надо выносить в отдельный пост.
Как многие отмечают там в комментариях статья отстой, человек не разбирается и смешал всё в кучу, попробую поделиться своими выводами от использования разных разметок.
Читать дальше →
Total votes 15: ↑13 and ↓2 +11
Views 17K
Comments 55
1