Руководство по стилю контента

Добро пожаловать в руководство по документации MODX для авторов и участников.

Это руководство содержит основные правила, советы и предложения для людей, пишущих или редактирующих документацию для MODX. Когда разные документы используют одни и те же рекомендации, они становятся более удобными для пользователя, последовательными и более простыми для объединения и повторного использования. Поэтому мы настоятельно рекомендуем всем участникам следовать этим рекомендациям на благо сообщества.

Это руководство содержит основные правила, советы и предложения для людей, пишущих или редактирующих документацию для MODX, ориентированную на стиль письма. Когда в разных документах используются одни и те же рекомендации, они становятся более удобными, последовательными и более простыми для комбинирования и повторного использования. Если можете, следуйте этим рекомендациям.

Используйте американский английский¶

Во всем MODX американский английский является стандартом для всех письменных материалов.

Основные правила¶

-our или -or¶

Британские слова, оканчивающиеся на -our (например, аромат), теряют свое U при переводе на американский английский Например, аромат становится ароматом, цвет становится цветом. То же самое обычно относится к словам с - наш в середине, поэтому поведение становится поведением.

Двойные согласные¶

Когда вы переводите глагол в форму -ing, помните, что в американском английском есть одинарный, а не двойной согласный. Например, путешествие становится путешествием, выравнивание становится выравниванием и т.д.

Список распространенных вариантов написания в Великобритании и США¶

Для более полного списка см. Wikipedia

Правила написания¶

Вот некоторые правила, которые делают документы более четкими, точными и легкими для понимания.

Будь проще¶

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

Неправильно¶

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

Правильно¶

Производственный модуль позволяет пользователям определять планы процесса, рабочие требования и рабочие усилия. В этом разделе описывается, как функционируют процессы, которые производят промежуточные и конечные товары.

Времена¶

Всегда используйте настоящее время. Избегайте прошлых или будущих времен, если это возможно.

Кроме того, попробуйте не использовать must, have to, ​​need to, ​​will, should и подобные формы.

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

Неправильно¶

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

Правильно¶

Нажмите возврат, чтобы перезагрузить систему.

Агрессивный язык¶

Избегайте использования агрессивных описаний.

Неправильно¶

Ударьте return, чтобы перезагрузить систему.

Правильно¶

Нажмите return, чтобы перезагрузить систему.

Используйте активный голос¶

Пишите, используя активный голос, где это возможно.

Использование активного голоса облегчает чтение и понимание документации. Это также помогает уточнить, кто что делает, и это важно в пользовательской документации.

Если вы пишете сообщение об ошибке, допустимо использовать пассивный голос, чтобы не обвинять пользователя.

Использовать третье лицо¶

Там, где это возможно, используйте императив от третьего лица. Например:

Запустить установочный скрипт¶

лучше, чем:

Вы должны запустить скрипт установки¶

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

Старайтесь не называть пользователя «пользователем», например: «Пользователи должны входить в систему, используя свои пароли», если вы не проводите четкое различие между пользователями и кем-то еще, например: администратор

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

«Ошибка: неверный пароль»

лучше, чем:

«Ошибка: вы ввели неверный пароль»

Пунктуация¶

Восклицательные знаки¶

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

Сокращения¶

Не используйте апостроф для множественных сокращений: #### Неверно: используйте окно заказа на покупку для создания заказа на поставку ** Право **: используйте окно заказа на покупку для создания заказа на покупку

Нет личных мнений¶

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

Неправильно¶

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

Правильно¶

Выберите параметр Отчет, чтобы создать полный отчет о данных клиента. Также есть возможность экспортировать данные и создавать отчеты из сторонних приложений.

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

«Приложение легко настроить с помощью мастера».

Капитализация¶

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

Избегайте гендерной дискриминации¶

Читателями программной документации являются мужчины и женщины. К сожалению, в английском языке нет личного или притяжательного местоимения, обозначающего гендерную нейтральность. Избегайте использования выражений, которые относятся к конкретным гендерным формам. Обратите особое внимание на местоимения she, he, him или her.

Неправильно¶

У каждого пользователя есть свой домашний каталог.

Правильно¶

У каждого пользователя есть домашний каталог.

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

Пользовательские истории и сценарии обучения являются хорошим местом для демонстрации разнообразия.

Помните, что в английском языке только люди имеют пол. Большинство других существительных являются нейтральными.

Опишите только текущую функциональность¶

Избегайте разговоров о будущих функциях или планах для продукта или приложения.

Неправильно¶

Графика может быть сохранена в виде изображения GIF. Поддержка новых форматов будет добавлена ​​в следующих версиях.

Правильно¶

Графика может быть сохранена в виде изображения GIF.

Терминология¶

Флажок¶

Флажок это все одно слово (не флажок). Флажки либо установлены, либо сняты.

Например:

«Установите флажок Active, чтобы сделать поле видимым» «Снимите флажок Active, чтобы сделать поле невидимым».

Войти против Войти¶

Глагол Войти и Войти "Войти с использованием предоставленного пароля" "Войти MODX ERP" Существительное или прилагательное "Логин" Вам понадобится действительный Логин учетные данные для использования системы"

Не logon, log, log-in и т.д.

Испанский - Английский ложные Друзья и другие¶

Если испанский является вашим первым языком, остерегайтесь следующих распространенных ошибок

Dudas / doubts¶

«Dudas» в английском языке обычно имеет довольно отрицательное значение. Лучший перевод - это вопросы или запросы.

Неправильно: Если у вас есть какие-либо сомнения относительно MODX, обратитесь к вики. Лучше: если у вас есть какие-либо вопросы о MODX, обратитесь к вики.

Его / ее¶

В английском только люди имеют пол. Вещи всегда нейтральны и принимают притяжательное местоимение «свое» (без апострофа).

Жирный и Курсив¶

Поскольку мы используем разные источники документации, в том числе Mediawiki, используется ограниченное количество стилей форматирования:

• Жирный. Используйте экономно для выделения или для выделения путей к файлам или имен опций, например:

В меню Файл выберите Новый.

• Курсив. Используйте его при цитировании сниппета текста из другого источника, сниппета текста на другом языке или в качестве примера, например, образца текста для ввода в текстовое поле.

Пути к файлам / меню¶

Пути к файлам (то есть определенные местоположения файлов) должны соответствовать стандарту "Directory/subdirectory/file.extension".

• Для навигации по меню (например, начиная новый документ) выделите все целиком и используйте>, чтобы отделить пункты меню.

Ориентируйте пользователя, начиная с того, что ему нужно искать. Например:

В меню Файл выберите Документ> Новый> Шаблон.

A не:

Выберите Документ> Новый> Шаблон в меню Файл.

Наименование изображений и снимков¶

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

Платформа¶

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

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

Неправильно¶

Для запуска MODX POS дважды щелкните start.bat

Правильный¶

Linux¶

Чтобы запустить MODX POS, запустите сценарий оболочки start.sh, либо щелкнув его, либо набрав ./start.sh из оболочки.

Windows¶

Чтобы запустить MODX POS, запустите командный файл start.bat, дважды щелкнув по нему или введя start.bat из командной строки.

Другие соглашения¶

При описании вариантов всегда начинайте слева направо и сверху вниз.

• Если у вас есть список элементов (например, список файлов для загрузки), упорядочите их в алфавитном порядке, если нет более очевидного логического порядка.
• Постарайтесь соответствовать тому, как вы описываете подобные процессы. Например, не смешивайте навигацию мыши с нажатиями клавиш в одной и той же процедуре, если это действительно не нужно. В общем, выберите свой стиль взаимодействия (меню, нажатия клавиш и т.д.) И придерживайтесь его во всем документе.
• Не используйте сокращения (не, ты и т.д.)

Писать для глобальной аудитории¶

исходное программное обеспечение является глобальным по определению. Имейте в виду, что люди со всего мира имеют доступ к нему и соответствующей документации¶

Некоторые важные рекомендации:

• Избегайте использования имен людей, адресов и другой типовой информации, которая не распространена на английском языке.

• Помните, что валюты и форматы для представления дат и чисел не одинаковы во всех частях света.

Форматирование страницы и разметка¶

Существует ограниченный набор элементов форматирования для упрощения работы редакторов и обеспечения согласованного форматирования для читателей. Ниже показано, какие форматы доступны для HTML и специальные форматы для документации MODX.

Разрешенная HTML-разметка¶

Специальные форматы¶

Другие элементы HTML, такие как div, span, blockquotes, address и т.д. не должен использоваться. Это усложняет ведение документации и потенциально может создавать проблемы с макетами. Классы и идентификаторы не должны использоваться в разметке. Специальные классы, используемые при форматировании в HTML, создаются макросами специального формата, перечисленными выше.

Финальный контрольный список¶

Перед рассмотрением документа или внесением изменений рекомендуется выполнить следующий быстрый контрольный список:

• Понятно? Хорошо ли следует текст из абзаца в абзац?
• Это лаконично? Есть ли у него четкий стиль общения?
• Это связно? Текст прыгает от темы к теме?
• Это грамматически правильно? Вы проверяли правописание текста? Вы попросили носителя языка проверить текст