Документация в картинках

Сегодня я хочу признаться в своих недостатках программиста.

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

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

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

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

Спасение.
Блуждая по интернету, в поисках решения моей проблемы мне на помощь пришел graphviz и dot.
С помощью языка dot можно с легкостью описывать диаграммы и схемы, которые будут отражать архитектуру одинаковых компонент для web, iOs и Android; и рендерить во все что угодно: png/svg/jpeg.
Для dot существует огромное количество плагинов: под IDE, веб-сервисы вроде Confluence – это значит, что визуализацию документа можно получать не только из комманд лайна, но и внутри нормальных приложений.
А еще dot очень хорошо подходит для описания конечных автоматов => снятия вопроса неопределенности и необходимости додумывать.
Ну и конечно же, так как dot – это язык – фиксация изменения в текстовом файле, содержащем описание компоненты с помощью любой системы версионного контроля будет реализовано автоматически.

То что можно делать делать с dot и graphviz – смотрите ниже.



А вот текстовое представление:


Данный подход мне очень часто помогал как в разработке, так и в вопросах проведения презентаций. С использованием данного инструмента мне удавалось достаточно быстро и просто представить диаграмму/блок-схему и также быстро внести изменения. Язык dot достаточно простой, его очень просто освоить.

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

P.S.: я слукавил, я не люблю делать временные решения потому, что нет ничего более постоянного, чем временное. Надеюсь, что данный инструмент и подход поможет вам сэкономить время.