Советы по стилю DokuWiki

Несколько советов о том, как написать качественную вики-страницу.

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

• Для выделения слов и коротких отрывков текста используйте либо полужирный шрифт, либо курсив. Выберите какой-то один способ и придерживайтесь его.
• Используйте ненумерованные списки для утверждений, которые не зависят друг от друга. Чтобы развить свою мысль, используйте обычные последовательные предложения.
• Используйте сноски экономно и только для очень коротких дополнительных замечаний. Если по какой-то теме можно много сказать, создайте новую страницу вики.
• Таблицы позволяют значительно улучшить читаемость структурированных данных. Вставляя таблицу, не забудьте дать осмысленные заголовки и подпись к таблице в целом.
• Большие таблицы обычно трудно редактировать. Рассмотрите альтернативу в виде многоуровневого списка.

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

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

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