Semantic Line Breaks
Вся техническая документация наших проектов пишется в формате Markdown.
Это простой и удобный формат, который можно читать даже в сыром виде без
постобработки.
Для того чтобы документы в формате Markdown оставались пригодными для чтения
и последующего редактирования, я рекомендую придерживаться
соглашений Semantic Line Breaks.
Это набор простых правил форматирования, предполагающих отбивку блоков текста,
списков и других элементов разметки пустыми строками.
Немного удивлён тем, что эти соглашения остаются малоизвестными многим разработчикам. А их соблюдение даёт массу преимуществ:
- повышается читаемость документа в чистом виде;
- повышается простота инспекции изменений, иными словами, будет сильно проще
просматривать вывод команды
git diff [--word-diff]; - повышается простота внесения изменений в документы, отформатированные с
помощью
Semantic Line Breaks.
Для иллюстрации я приведу два фрагмента.
Lorem Ipsum - это текст-"рыба", часто используемый в печати и вэб-дизайне. Lorem Ipsum является стандартной "рыбой" для текстов на латинице с начала XVI века. В то время некий безымянный печатник создал большую коллекцию размеров и форм шрифтов, используя Lorem Ipsum для распечатки образцов.
- Пункт 1
- Пункт 2
- Пункт 3
Давайте применим к примеру выше Semantic Line Breaks:
Lorem Ipsum - это текст-"рыба", часто используемый
в печати и вэб-дизайне.
Lorem Ipsum является стандартной "рыбой" для текстов
на латинице с начала XVI века.
В то время некий безымянный печатник создал большую коллекцию
размеров и форм шрифтов, используя Lorem Ipsum
для распечатки образцов.
- Пункт 1
- Пункт 2
- Пункт 3
Применив простые правила, мы получили гораздо более читаемый документ на выходе.
Соглашения Semantic Line Breaks подходят не только для формата Markdown. Их
стоит придерживаться при редактировании как обычных текстовых файлов, так и
файлов использующих другие языки разметки, например, reST или AsciiDoc.