Правила оформления статей
Материал из AutoPark
Правила оформления статей
- Описание полей делать с помошью definition list. См. пример.
- Таблицы применять только в случае крайней необходимости (пока известен только один пример).
- Оформление посредством пробелов в начале строки не применять.
- Наименование поля – НЕ подчеркнуты – обычным шрифтом.
- Красных ссылок быть не должно. Если требуется сослаться на статью, которой нет, то следует оформить ее хотя бы одним предложением, правильно указать перечень категорий + категория "Статьи в работе".
- Ссылки следует расставлять только в первом вхождении понятия на странице. В некоторых случаях – и повторно тоже.
- Раскрытие значений перечислимого типа делать только в том случае, когда это важно для понимания. Предельный случай ерунды – раскрытие значений "Да" и "Нет".
- Текст, который нужно показать моноширинным шрифтом, следует помещать в блок
<code></code>
:123456789АБВГД
ДГВБА987654321
- Текст, который читатель документации должен интерпретировать как неразрывный, следует помещать в специальные кавычки («»): «Текст, который необходимо интерпретировать как неразрывный, несмотря на то, что он очень длинный и занимает несколько строк. Что такое "несколько строк"? Это больше, чем одна строка. На любом, даже очень (очень-очень) большом мониторе. И на любой, даже очень (очень-очень) большой бумаге. Любым, даже очень (очень-очень) маленьким шрифтом.»
- Моноширинный неразрывный текст: «
Текст, который необходимо интерпретировать как неразрывный, несмотря на то, что он очень длинный и занимает несколько строк. Что такое "несколько строк"? Это больше, чем одна строка. На любом, даже очень (очень-очень) большом мониторе. И на любой, даже очень (очень-очень) большой бумаге. Любым, даже очень (очень-очень) маленьким шрифтом.
» - Для выделения текста использовать
<b></b>
. Не использовать написание слов прописными буквами. - Грамматических ошибок и описок в документации быть не должно! Следует использовать любые доступные средства для контроля. Например, Firefox. А также широко раскрывать глаза.
- Короткие пути и кнопки оформлять по стандарту.
- Не писать раздел "Применение", ибо есть стандартная страница с перечнем обратных ссылок на страницу ("Ссылки сюда").
- Примеры, это возможно, хорошо, но о чем говорят примеры в виде "код, наименование"?
- Применять "№", а не "N".
- Сложные списки. Пример:
- Элемент 1
- Подуровень 1 элемента 1
- Подуровень 1 элемента 1
- А вот надо продолжить писать про элемент 1. Применяем конструкцию
*#:
. Вот такой длинный-длинный-длинный длинный-длинный-длинный длинный-длинный-длинный длинный-длинный-длинный длинный-длинный-длинный текст.
- Продолжаем - элемент 2
- Элемент 1