а можешь дать пример исходной таблицы и команду, которой запускаешь pandoc?

Не хватает пустой строки между абзацем и таблицей. Из-за этого всё содержимое таблицы парсится просто как текст. Вот так работает:

# Документ с таблицей

Таблица 1:

| Параметр | Значение | Ед. изм. |
| :------- | :------: | :------: |
| Длина    |    3     |    м     |
| Ширина   |    1     |    м     |
| Высота   |    2     |    м     |

Спасибо! Да, так сработало.

Friendly Asked Questions #2 — про документацию

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

Ответы дали авторы каналов Уютный Адочек, DocOps и The Know All
А мы ждём ваших вопросов в: https://forms.gle/sKyaEuqQMMyFJBxJ8

@the_know_all — Лана Новикова

Документация — один из способов организовать коммуникацию по какому-то каналу. Это решение, а давайте вернемся к проблеме. Зачем документация и какую вашу проблему и проблему бизнеса она решит?
Проблема — неосведомленность сотрудников о том, что делается в другом проекте. Эту проблему может решить не только документация, но и, например, периодические демо, сессии обмена знаниями, shadowing (когда периодически специалисты из одного проекта переключают контекст и работают в паре с коллегами из другого в формате «тени»). Техническому директору это надо «продавать» в его терминах: ускорение разработки, снижение эскалаций, снижение рисков инцидентов.
В тему организации обмена знаниями между отделами есть хороший доклад Марии Палагиной


@docops — Ник Волынкин

Давай тут разделим проблему на три части.
1. Команда не пишет. Стань первым, кто начнёт это делать. Когда будешь в чем-то разбираться — делай заметки. Так у команды будет хороший пример. Постарайся рассказывать команде о том почему и как это делаешь, и замечать, как твоя работа реально будет помогать коллегам.
2. Тимлид не поддерживает идею документирования. Вы, наверное, сейчас теряете время на погружение в задачу и на изобретение велосипедов, теряете мотивацию людей, плохо учитесь на ошибках (и будете их повторять). Всё это напрямую мешает работе тимлида и ставит его задницу под удар начальства. Не предлагай тимлиду писать доки — предлагай ему помощь в его работе.
3. Техдир идёт на конфликт. Лучше приходить к техдиру с тем, что уже работает хоть на небольшом масштабе. И ещё, техдиру нужен запрос, который можно решить только на его уровне. Плохо: "Сделай так чтобы мой тимлид заставил нас писать доки". Хорошо: "Мы начали писать анализ инцидентов, это помогает, давай это распространим на всю компанию".

@lovely_it_hell — Цупко Игорь

Можете ли вы писать документацию самостоятельно, подавая пример коллегам? Если в компании не выделяют время на изменения и инициативы — возможно пора поменять компанию.
Описанные реакции — странные. Троллинг и агрессия руководителя в ответ на инициативу подчинённого — звучит не здорово.
Если я правильно понимаю, вы хотите вдохновить коллег, побудить их к действиям. Попробуйте покидать им хороших примеров (возможно вы просто сейчас более "насмотрены" на хорошую доку, чем они), докладов, пописать короткие посты в чатики команды — но без нажима и требований. Вода камень точит и со временем какие-то идеи осядут в головах.

в каждом из 3 ответов сквозит своя стилистика

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

Ник Волынкин декомпозирует на список и формирует ответ на каждую проблему из списка. Офигенный подход техписа)

Цупко Игорь написал самый живой текст. Этот текст лучше всего воспринимается сознанием, его читать одно удовольствие)
Наверняка у Игоря есть опыт работы  писателем статей для прессы)

Спасибо за хороший отзыв. Для меня ответ Ланы наполнен смыслом. Может быть, потому что тема про каналы коммуникации мне очень хорошо знакома. А у Игоря есть опыт работы «директором по неизвестному», это ещё круче, чем статьи для прессы :)

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

И это отличный вопрос

в смысле, отличное предложение вернуться на шаг назад

Я отвечала так, как я бы отвечала в реальной жизни, если бы мне задали вопрос в кулуарах, на конфе, на кухне в офисе, а в реальной жизни да, бывает мысль спутана

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

Там если прочитать вопрос, то есть логический разрыв между (каждый раз когда дают задачи на незнакомый проект — это боль.) и (Хочу, чтобы команда начала писать документацию). Вот мне он был не ясен, как из А получилось Б, в жизни, в диалоге я бы сначала прояснила, как он пришел к Б

Мне не нравится мысль, которая сквозит в ответах:
- Надо продавать..!
Мы, работники компании, являемся единой командой, у каждого из нас свои функциональные обязанности. И в первую очередь вся наша деятельность нацелена на выполнении стратегии компании.
Поэтому, когда мне, члену команды, нужно продавать то, что априори необходимо, то это очень странно и вызывает вопрос о компетенциях менеджмента.
Я, как техпис не должен продавать что-то менеджерам. Хороший управленец должен сам предвидеть, планировать и внедрять.
Задача специалиста только в том, что он даёт представления о тех инструментах, которые позволят добиться выполнения самого главного в деятельности компании - формировании успешного продукта.
Извините, но если менеджмент не понимает, что держать 1С на сервере 10-ей давности это неправильно, то это не задача ДевОпса клянчить, доказывать и продавать.
Это задача менеджмента.
Задача техписа создать текстовое представление (а иногда и визуальное) о продукте, включая и то ,как же пользоваться этим продуктом. Если менеджмент допускает, что продукт компании не будет обладать такой часть как документация, то техпис не должен продавать менеджменту идею. что документация нужна (еще и полезна).
Да, я считаю, что основная тяжесть документирования продукта, а точнее по координации всех сотрудников компании, которые создают продукт, ложится именно на менеджмент. Для этого и существуют различные роли в самом менеджменте.
А техпис для менеджмента компании помощник, но никак не продавец.
====
Сорь, за длиннопост в непрофильном канале )

Честно говоря, если техдир действительно «агрится и троллит», то да - у него нет права на подобное поведение.


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

Условно говоря: у айфона нет технической документации.

Я умышленно привел две крайности, реальность конечно будет в середине или даже сочетать в себе эти две крайности. И нет, айфон с такими крайностями не сделать конечно :)

тут не снежинка-техпис, тут снежинка-девопс-инженер )

Ну кто угодно.

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


Поэтому если человек находится на позиции техдира, компания успешна, его не выгнали и он «агрится и троллит», то стоит получше посмотреть и оценить его поведение и свое его восприятие.

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

5 коп
Комментарий к посту
В любом ответе всегда будет присутствовать специфика «должности» того, кто пишет.
Все три ответа на вопрос написаны руководителями (возможно, я не прав). Насколько ответы 3-х менеджеров будут охватывать разные стороны видения на поставленный вопрос девопса - это уже отдельный вопрос.

Комментарий к поставленному вопросу
Сам вопрос обладает неполнотой и размытостью. «Каждый раз», «неизвестный проект», «хочу...начала писать», «тимлид пожимает», «техдир троллит».
Похоже, что тимлид — пожиматель плечами. А техдир — вообще тролляка 80 лвл.
Непонятна связка между «хочу - стоит ли задача».
Непонятно донёс ли суть «сложности» девопс до тимлида хотя -бы...
«Если б мне платили каждый раз, каждый раз, когда ты...» (слова из одной песни вспомнились).


Комментарий к части автора канала
Импонирует п. 3, Ника.
Подход, когда «предлагают» что-то конкретное менеджеру (руководителю любого уровня), вероятно найдёт больше откликов у того же менеджера, чем в случае «плак плак, не получается».
Готовое решение, пусть даже, которое требует внимание (доработки, действий и т.д.) менеджера и его изменение, «дешевле» в затратах по времени, чем в цепочке понять вопрос->выработать решение с 0->внедрить.
Предлагать готовое решение (как бы пафосно не звучало) уже начало моста для решения

Божечки-кошечки, какой ужас.

Первое правило любой постановки задачи для других – Вам необходимо донести необходимость этой задачи.
И здесь всё упирается в soft skills.
Составляйте проект, обосновывайте необходимость, назначайте митинг.
Документируйте свою работу.
Результат может быть разным:
1. Вы поняли, что нет необходимости в таком канале коммуникации как "документация" (маловероятно).
Откажитесь от идеи, если документация не нужна.
2. Вы смогли убедить остальных, что это не блажь, не прихоть, а действительно необходимо.
Поздравляем, вы частично добились результата.
3. Вы смогли убедить остальных, что это не блажь, не прихоть, а действительно необходимо. Были назначены ответственные за постановку процесса документирования.
Поздравляем, вы добились результата.
4. Вы оказались недостаточно аргументированным и решение о необходимости документирования не было принято.
Увы, боль и разочарование. Вам есть куда расти.
5. Вы добились своего и "убедили" ответственных за процессы разработки, но всё как и раньше не документируется...
Видимо дело действительно в других людях. Возможно Вам стоит сменить работу?