;
Иван Алякскин

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

06.12.2016 2427
IBS Training Center Telegram
Подписывайтесь на наш канал в Telegram:
больше материалов экспертов, анонсы бесплатных вебинаров и задачки для IT-специалистов
Подписаться
Сегодня я хочу признаться в своих недостатках программиста.

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

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

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

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

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

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



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

 digraph TrafficLights { node [shape=box]; gy2; yr2; rg2; gy1; yr1; rg1; node [shape=circle,fixedsize=true,width=0.9]; green2; yellow2; red2; safe2; safe1; green1; yellow1; red1; gy2->yellow2; rg2->green2; yr2->safe1; yr2->red2; safe2->rg2; green2->gy2; yellow2->yr2; red2->rg2; gy1->yellow1; rg1->green1; yr1->safe2; yr1->red1; safe1->rg1; green1->gy1; yellow1->yr1; red1->rg1; overlap=false label="PetriNet Model TrafficLights\nExtracted from ConceptBase and layed out by Graphviz" fontsize=12; } 
				

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

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

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



Расскажи друзьям:

Комментировать
Как не пропустить самое интересное?
Подписывайтесь на наш ежемесячный дайджест!
Спасибо.
Вы подписаны на ежемесячный дайджест.
Пользователь только что записался на курс ""
Спасибо!
Форма отправлена успешно.