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

Тогда уж старые добрые 80 символов. Хотя сейчас переходят на 120. Только зачем? Автоперенос никто не отменял.
https://github.com/Dealerdirect/guides/issues/2

Я всегда разбиваю по предложениям или по частям сложного предложения, так чтобы строка входила в экран.

Писать весь абзац в одну строку — плохо, потому что это ломает diff. Потом кто-нибудь исправляет одну запятую, но весь абзац считается изменённым. Во время ревью на это сложно смотреть. Некоторые инструменты для diff'а не умеют показывать, где именно в строке было изменение, так что приходится самому искать. А ещё, когда смотришь git blame, очень полезно видеть, поменялся весь абзац или одна строчка в нём.

Вот видно, что абзац написан давно, но потом поменялся уровень заголовка, а ещё потом — что-то в последней строке.

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

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

Но в моём примере выше эти правила не соблюдаются, там строго 80 символов, потому что этот документ сформировал pandoc. Когда сам пишу — переношу по логике текста.

А, ещё ссылки стараюсь выносить на отдельную строку. То есть

текст текст текст
[текст ссылки...](https://example.com)
дальше текст

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

Спасибо! Это очень хорошие практики

спасибо, никогда об этом не задумывался, хорошие практики!

Я вот тоже не задумывался, что это неочевидные практики. Спасибо, что указали мне на это. Пойду что ли пост напишу.

Добрый день!

Город Новосибирск, компания White Point

В развивающуюся компанию нужен технический писатель для написания ТЗ для 2 сайтов и мобильного приложения. У нас есть все идеи: что и как должно находиться и располагаться, нам осталось только перевести это все на технический язык.

Так как мы будем заниматься разработкой эффективных IT решений для бизнеса, мы набираем сейчас дизайнеров, разработчиков (они уже есть) и нам нужен технический писатель для выполнения заказов клиентов на создание как сайтов, так и приложений.

Оплата договорная.
Контакт: @ulianakochetova

#wanted_tw

Здравствуйте. Уверены, что создание ТЗ -  задача для тех. писателя, а не для аналитика?

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

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

То есть, у нас есть дизайнер и есть ТЗ начальное, но необходим технический писатель для того, чтобы на понятном им языке прописать что и где должно располагаться.

Кому им?

Нам, нашей компании.

Сейчас нам нужен технический писатель, чтобы помочь разработать ТЗ для 2 сайтов и 1 мобильного приложения.

ТЗ пишет аналитик для разработчиков до того как ПО создано.
туториал пишет технический писатель для пользователей после того как ПО создано.

Важно уточнить целевую аудиторию.
Если "им" состоит из группы программистов, то вам действительно нужен бизнес-аналитик.
А вот если "им" состоит из бизнесменов, или других _не_ технических специалистов, которым надо разжевать максимально просто, то в дополнение к бизнес-аналитику пригодится технический писатель.
Для технического писателя задачи аналитика не свойственны. Он может и сможет их выполнять, но вы переплатите за ненужные вам скилы и многопрофильного специалиста (а вы же написали, что занимаетесь "разработкой эффективных IT решений для бизнеса" - для вас переплачивать должно быть неприемлимо).