Comments 30
Ведь есть превеликое множество различных способов совместного онлайн-редактрования, начиная от того же Word в режиме совместной работы и заканчивая гугл-документами.
И если основная проблема работы через MS Word была в том, что нет возможности работать совмесно, то можно посмотреть в сторону редакторов документов, которые позволяют это делать.
Надеюсь, это не прозвучит как реклама, но если вам нужно совмесное редактирование + контроль версий + рецензирования документов, то в редакторах ONLYOFFICE все это есть.
Таблицы, конечно, требуются, но функциональности Markdown оказалось достаточно.
Попруйте плагин для форматирования таблиц под VS Code Table Formatter. Для создания, наверное, тоже есть.
Добавление и правка таблиц в md это вообще отдельное искусство, требующее терпения.
А разве нельзя использовать обычный html синтаксис для таблиц и других сложных элементов? Markdown поддерживает его внутри себя.
Я не утрирую, а правда считаю что будет довольно удобно.
Проблема в том, что исходный код такой страницы сильно проигрывает в наглядности маркдауну. И потому, если нужно будет что-то править, то придется немного покопаться в коде.
Markdown как раз хорош тем, что его можно открыть любым редактором текста, и все равно все будет понятно. Стоит ли жертвовать этим ради необходимых сложных элементов? Вопрос открытый.
Смысл такой, что markdown намного наглядней и проще HTML, за исключением таблиц. Лично у меня с таблицами особых пробелем нет, но я предложил парочку решений как можно облечить жизнь с ними: плагин или HTML. Можно ли придумать синтаксис для таблиц, чтобы он был удобный и с точки зрения дифов и с точки зрения редактирования? Вопрос открытый.
Pandoc умеет и toc, и нумерацию страниц, и титульную страницу.
На просторах интернета также есть классные темплейты для pdf.
Из того что вам нужно, там все есть.
Из недостатков:
- Ограниченная история, только линейная. В Git же можно как угодно бранчеваться и вертеть историей.
- Невозможность редактирования файлов локально в любом редакторе (только веб).
Из достоинств:
- Удобный WYSIWYG редактор – можно редактировать и создавать странице даже не разбираясь в синтаксисе разметке (как в Word).
- Скорее всего хорошая интеграция с другими сервисами Atlassian (Jira, BitBucket).
- Невозможно как-то связать историю «дерева», например если док состоит из нескольких страниц confluence под одним рутом, то не возможно их как-то синхронизировано откатить на «предыдущий релиз»
- Хромающая на 2 ноги работа с таблицами, особенно при выводе в тот же ворд. (Впрочем автору тут и git не особо помошник).
Из плюсов:
- Довольно большое количество плагинов как из коробки, так и то что можно добавить самому. Так что возможно сделать довольно гибкий функционал кросс-ссылок, дабы отследить в каком тикете Jira возник запрос на фичу (которую описавает дока), и в каком ее имлементировали и тд.
Вот именно что только средствами Word, да и то довольно ограниченно. Git работает на всех операционных системах, под него существует множество клиентов. Думаю не надо подробно расписывать возможности системы контроля, среди которых ветвление, версионирование, изменение истории.
А поддерживает ли Word относительные ссылки? Т.е. чтобы можно было указывать URL картинки в виде [image name](../image.jpg)
. Markdown поддерживает.
А для каких целей это требуется?
Хранить картинки отдельно от статьи, а также возможность их независимого редактирования. По сути несколько страниц маркдауна вместе с картинками — это уже статичный сайт или блог.
Обычно хватало абсолютных ссылок начиная с корня хранилища.
Они должны быть инвариантными относительно файловой системы отдельно взятого пользователя. Абсолютные ссылки относительно корня хранилища в моем понимании уже относительные.
В-вторых, сложно сравнивать методы. Я знаю детально сильные стороны изложенного мной подхода (слабые тоже), но не могу сказать, что осознаю до конца, что предлагаете вы. Поэтому могу говорить только какие-то общие вещи, а именно
1) подход с markdown выглядит более универсальным — вы можете конвертировать не только в Word, но и в другие форматы
2) лично для меня markdown очень удобен — в Word слишком много всего, и все должны делать это в едином стиле…
3) мне нравится разделение функций — Git отвечает за многопользовательскую работу, за версионирование и все что с этим связано, а Markdown — это информационная часть. В вашем же подходе, какие-то функции Git приходится делать силами Word и я не уверен, что там все это реализовано так же удобно
Но, еще раз хочу сказать, что описанный подход я не воспринимаю как лечение от всех болезней
В markdown+git я вижу такие преимущества.
- Документацию можно положить рядом с кодом, по моему мнению ему там и место.
- Изменение документации (при нормальном flow) привязывается к коду и коммиту которые его порадили
- Не требует дополнительного ПО, любой git SaaS умеет ренедерить Markdown
- Для редактирования не надо вылазить из привычного редактора (VSCode, IntelliJ)
- И главное это подсветка синтаксиса (если есть кто видел такую тулзу для google docs, скажите пожлайста)
Есть еще AsciiDoc — насколько я слышал, O'Reily на нем свой процесс построили.
Используйте GIT при документировании