b0g3r commented 5 years ago

Сейчас mindmap хранятся в .mm файлах формата FreeMind. У этого формата есть плюсы: поддерживается импорт в большинство mindmap-софта, популярен, открыт, изнутри — обычный xml.

Но есть и критичные недостатки:

содержимое файлов не человеко-читаемо, через гитхаб не поревьюишь
нет CLI утилит для генерации .mm в картинки (и не будет) (но есть в D3.js)
из предыдущего пункта вытекает сложный CI для автообновления зависимого контента
проект не развивается, последний релиз более трёх лет назад

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

Пример файла:

@startmindmap
* Teamlead Roadmap
left side

** Personal Skills
***_ Развитие себя
****_ Умение учиться
****_ Рефлексия
****_ Выработка привычек
***_ Отношения
****_ Эмпатия
****_ Эмоциональный интеллект
****_ Понимание ценности различий
***_ Мышление
****_ Системное мышление
****_ Стратегическое видение
****_ Принятие решений
***_ Стили управления
***_ Коммуникации
***_ Тайм-менеджемент

@endmindmap

Результат:

Кроме простоты и отсутствия необходимости что-то качать себе на компьютер (онлайн-редакторы) из этого формата ещё и легко генерить png/svg, а в .svg можно ещё и добавлять интерактивные ссылки.

Если мы всё таки собираемся перейти на plantuml, то надо решить, оставлять или нет обратную совместимость с .mm. В целом, генерация .mm из plantuml — задачка на пару вечеров.

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

Связанные issue: #92, #91, #20

vvscode commented 5 years ago

https://www.npmjs.com/package/json-to-freemind например, и хранить json

а формат .mm генерировать как часть publish процесса

vvscode commented 5 years ago

Опять же есть https://www.freeplane.org/wiki/index.php/Command-line_options_and_configuration (хотя это и костыль)

ИМХО - использование yaml позволит разбить большую карту на подфайлы, а потом из этого можно генерировать любой формат

Ну и читабельность само собой

DevAlloy commented 5 years ago

Для чего используют .mm файл:

Обновить структуру дерева (происходит редко)
Нарезают себе или своим сотрудникам дерево (основной юзкейс)

Нам фидбек на эту тему особо не прилетал, но лично мне не очень удобно править .mm файл. FreeMind довольно страшный и неудобный, а MindNode не сохраняет обратно в .mm. Нужен инструмент, который позволит людям быстро и удобно нарезать дерево. Мне .puml видится таким инструментом.

С учетом того, что у нас только одна, пусть и достаточно большая карта, мы можем менять форматы относительно быстро.

Я за то, чтобы сделать .puml источником правды:

Дропнуть .mm в пользу .puml или генерить его из последнего
Дропнуть links.json, в .puml можно использовать ссылки
Генерировать README.md из .puml.

enrey commented 5 years ago

Не раскрыта замена удобного визуального редактора в случае нового формата. Майндмапы любят за хоткеи. Все-таки нажать Ins на узле многим проще чем "искать текст в тексте" а потом добавлять **** по уровню вложенности.
Отображение (рендеринг) Puml можно встроить в markdown github разметку и тогда конвертация в картинки на ci не понадобится - это как плюс тикета.

kbakba commented 5 years ago

Любой MindMap (далее ММ) в конечном итоге это просто многоуровневый список, иногда со ссылками на другие элементы этого списка.

Если мы говорим про редактирование то проще весь список иметь в виде одного или нескольких файлов в удобных для редактирования простым текстовым редактором, типа Markdown или YAML (можно и puml только не понятно зачем в него вникать, если двух предыдущих достаточно). Дальнейшее его отображение это дело техники – его можно сконвертировать и в .mm и в .puml и отрендерить в .png и .svg.

kbakba commented 5 years ago

Отображение (рендеринг) Puml можно встроить в markdown github разметку и тогда конвертация в картинки на ci не понадобится - это как плюс тикета.

Github так умеет?

kbakba commented 5 years ago

Не раскрыта замена удобного визуального редактора в случае нового формата. Майндмапы любят за хоткеи. Все-таки нажать Ins на узле многим проще чем "искать текст в тексте" а потом добавлять **** по уровню вложенности.

Ну искать в внутри MM все равно придется. А все современные редакторы умеют создать новый элемент списка по нажатию на «Enter».

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

b0g3r commented 5 years ago

Любой MindMap (далее ММ) в конечном итоге это просто многоуровневый список, иногда со ссылками на другие элементы этого списка.

За одним исключением: mindmap это не просто многоуровневый список, а многоуровневый список с двумя направлениями, т.е. нужна возможность разворачивать одни ветви вправо, а другие влево. Можешь предложить как в такой концепции это сделать в yaml? Если получится удобный способ, то я тоже за .yaml как за формат хранения.

kbakba commented 5 years ago

За одним исключением: mindmap это не просто многоуровневый список, а многоуровневый список с двумя направлениями, т.е. нужна возможность разворачивать одни ветви вправо, а другие влево. Можешь предложить как в такой концепции это сделать в yaml?

на самом деле не в два, а как минимум четыре (еще верх-низ), но это не важно Любой элемент списка может быть или строкой или объектом с полями:

title: string*
color: enum
direction: enum
children: ListItem

только title является обязательным. Валидировать по схеме.

Пример в YAML:

--- 
title: "Teamlead Roadmap"
children: 
  - title: "Personal Skills"
    color: red
    direction: right
    children: 
      - title: Развитие себя
        color: blue
        link: ./Умение учиться
      - Умение учиться
      - Рефлексия
      - "Выработка привычек"

  - title: Отношения
    color: yellow
    direction: left
    children: 
      - Эмпатия
      - "Эмоциональный интеллект"
      - "Понимание ценности различий"
  - title: Мышление
    children:
    - Системное мышление 
    - Стратегическое видение 
    - Принятие решений
  - "Стили управления"
  - Коммуникации
  - Тайм-менеджемент

В markdown можно использовать html для дополнительной информации. Или направление кодировать символом списка- - право * - лево, т.к. это актуально только для первого уровня.

пример markdown, в котором использованы оба приема:

* Teamlead Roadmap:
  * Personal Skills <data direction=left color=red/>
      - Развитие себя
      - Умение учиться
      - Рефлексия
      - Выработка привычек
  * Отношения <data direction=left color=yellow/>
      - Эмпатия
      - Эмоциональный интеллект
      - Понимание ценности различий
  - Мышление <data direction=right color=green/>
      - Системное мышление
      - Стратегическое видение
      - Принятие решений
  - Стили управления <data direction=right color=purple/>
  - Коммуникации
  - Тайм-менеджемент

kbakba commented 5 years ago

Я за markdown, только потому что работать с ним удобно работать на github. И иметь все в одном формате удобнее.

etolstoy commented 5 years ago

Я за любой текстовый формат, к которому мы прикрутим автоэкспорт mm-файла и png. Как минимум я регулярно пользуюсь возможностью открыть роадмап в MindNode/Freemind и поиграться там с ним.

b0g3r commented 5 years ago

В целом — я сделал утилиту plantuml2freemind, она есть на PyPI, всё по-взрослому.

Собрана из говна и палок, но базовый .puml в OrgMode переводит в честный .mm. (через промежуточный структурный .yaml)

Осталось:

[x] Выбрать один из форматов plantuml mindmap: orgmode, arithmetic, markdown (я за orgmode)
[x] Добавить в парсер plantuml вытаскивание цвета и в генератор freemind запихивание цвета в edge или node: https://github.com/b0g3r/plantuml2freemind/issues/13
[x] Добавить в парсер plantuml вытаскивание ссылок: https://github.com/b0g3r/plantuml2freemind/issues/16
[x] Добавить CI, генерирующий .mm файлы и .png/.svg по plantuml-файлам
[x] Перевести все существующие схемы в .puml

Всё можно делать параллельно

etolstoy commented 5 years ago

Посмотрели с @DevAlloy. Нам норм и orgmode, и markdown – тут выбирай сам. В целом огонь, спасибо, что делаешь :) Если создашь issues, попробуем тоже подключиться к разработке.

b0g3r commented 5 years ago

По раскрашиванию и ссылочкам уже есть ишьюс, добавил их в предыдущий комментарий :top:

etolstoy commented 5 years ago

179

etolstoy commented 4 years ago

Отличные новости! Благодаря огромной помощи @b0g3r мы закрываем этот тикет. Теперь вся структура в roadmap.puml, mindmap, png и Readme генерируются автоматически.

tlbootcamp / tlroadmap

Перевести tlroadmap из FreeMind в plantuml #160

179