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