bga68 (bga68) wrote,
bga68
bga68

Categories:

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

http://www.luxoft-training.ru/blog/mlog/552.html?r1=socialicons


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


Алякскин Иван 06.12.2016 09:20:55

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

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

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

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

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

Спасение.
Блуждая по интернету, в поисках решения моей проблемы мне на помощь пришел 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.: я слукавил, я не люблю делать временные решения потому, что нет ничего более постоянного, чем временное. Надеюсь, что данный инструмент и подход поможет вам сэкономить время.

Tags: human resources, time, время, обучение
Subscribe

  • Post a new comment

    Error

    default userpic

    Your IP address will be recorded 

    When you submit the form an invisible reCAPTCHA check will be performed.
    You must follow the Privacy Policy and Google Terms of use.
  • 0 comments