Правила хорошего стиля

Несколько советов, как писать хорошие Wiki-страницы.

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

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

• Соблюдайте правила грамматики языка, на котором вы пишете. Для английского языка не забывайте использовать артикли.
• Соблюдайте правила пунктуации - предложения должны быть отделены друг от друга.
• Пытайтесь писать коротко и ясно. Избегайте большого количества сложно-сочиненных предложений. Когда вы написали страницу, перечитайте ее и попробуйте упростить слишком длинные предложения.
  
• Решите, как вы будете обращаться к вашим читателям. Так как DokuWiki хорошо подходит для написания документации, вам часто придётся давать инструкции вашим читателям о том как выполнить то или иное действие. При этом вы можете использовать несколько форм обращения к читателю: повелительное наклонение («Сделайте это!…», более мягкую форму мы/вы («После этого мы щелкаем (вы щелкаете) на кнопке…»), безличную форму («Необходимо сделать то-то и то-то») или форму с «я» («После этого я добавил кнопку на форму главного окна…»). Не смешивайте различные формы обращения.
• Перед тем как сохранить страницу, проверьте текст на отсутствие орфографических и грамматических ошибок. Если ваш текст будет содержать много ошибок, это уменьшит доверие к вашим высказываниям несмотря на глубину и продуманность высказанного.
• Придумайте свой стиль. Не пытайтель принудить себя писать в неудобной манере - написанное будет звучать ненатурально и скорее всего текст будет неприятно читать.

• Если вы сталкиваетесь с термином, который требует подробного разъяснения, добавьте новую страницу для этого термина и сделайте на неё ссылку.
• Перечитайте вашу страницу перед тем, как закончить над ней работу и добавьте ссылки на уже существующие страницы с описанием главных терминов.
• Не добавляйте ссылки каждый раз, когда встречается определённый термин. Добавьте ссылку только на первом вхождении или в наиболее подходящем месте и, возможно, приведите дополнительную ссылку в разделе «Смотри также» в конце документа.
• Предоставляйте ссылки на источники изображений, данных и цитат.
• Старайтесь добавлять строку «Смотрите также:» в конец страницы. Дальше укажите вики-страницы, которые наиболее близко связаны с темой этой страницы.

• «Картина красноречивей тысячи слов.» Изображение может сказать даже больше чем вы хотели. Humans tend to question the authenticity of images less than that of language. Короткое текстовое описание лучше чем ничего или чем некорректное изображение.
• Также как и с таблицами, всегда подписывайте изображения так, чтобы было ясно, что вы хотите показать. (Например «Рис. 3.2: Amateur photograph showing a frob shorbeling a guzz in a wuzzle.»)
• Если вы не автор изображения, укажите источник (возможно со ссылкой) и указанием автора (copyright).
• Не ссылайтесь на изображения с других сайтов, если не получили на это специального разрешения. Это приводит к расходам трафика сайта-обладателя изображения. Загружайте изображения в wiki, если есть такая возможность.
• Если изображение занимает больше чем треть страницы, используйте ссылку с инструкцией по изменению размера для вставки эскиза изображения.

Источник: не сохранилось