4. Стиль изложения

Суть стиля написания документации Ansible — короткие предложения, естественно перетекающие друг в друга. Меняйте структуру предложений. Меняйте подлежащие. Обращайтесь к читателю напрямую. Задавайте вопросы. А когда читатель привыкнет к темпу коротких предложений, напишите более длинное.

• Пишите так, как говорят реальные люди...
• ...но старайтесь избегать сленга и разговорных выражений, которые могут плохо переводиться на другие языки.
• Выражайте большие мысли маленькими словами.
• Будьте конкретны. Расскажите читателю точно, что вы хотите, чтобы он сделал.
• Будьте честны.
• Короткие предложения демонстрируют уверенность.
• Правила грамматики предназначены для того, чтобы их нарушать, но только если читатель понимает, что вы это делаете.
• Выбирайте слова с меньшим количеством слогов для более быстрого чтения и лучшего понимания.
• Представьте копию как один на один разговор, а не как речь. Сложнее игнорировать того, кто разговаривает с вами напрямую.
• Если возможно, начинайте предложения, ориентированные на задачу (те, которые направляют пользователя на выполнение действия), с глаголов действия. Например: Найдите ПО... Свяжитесь со службой поддержки... Установите медиафайл.... и так далее.

4.1. Активный залог

Используйте активный залог («Запустите Linuxconf, набрав...») вместо пассивного («Linuxconf можно запустить, набрав...») всякий раз, когда это возможно. Активный залог делает чтение более живым и интересным. Также старайтесь избегать будущего времени (или использование слова «будет») по возможности. Например, будущее время («На экране отобразится...») читается хуже, чем активный залог («На экране отображается»). Помните, что пользователи, для которых вы пишете документацию, чаще всего обращаются к ней во время работы с системой, а не после или до работы с ней.