Написание документации

Новая документация должна хорошо сочетаться с остальной документацией Elgg.

Тестирование документации локально

Elgg имеет скрипт grunt, который автоматически собирает документацию, открывает её в окне браузера и автоматически перезагружает при внесении изменений (перезагрузка занимает всего несколько секунд). Для использования этих скриптов вам необходимо установить yarn и sphinx.

cd path/to/elgg/
yarn
grunt

Всё так просто! Grunt продолжит работать, отслеживая изменения в документации и автоматически пересобирая её.

Примечание

Возможно, вам потребуется установить „sphinxcontrib-phpdomain“. Вы можете сделать это с помощью следующей команды: pip install -U sphinxcontrib-phpdomain

Следуйте существующей организации документов

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

intro/*

Это всё, что нужно знать совершенно новым пользователям (установка, функции, лицензия и т.д.)

admin/*

Руководства для администраторов. Ориентированы на задачи.

guides/*

Руководства по API для разработчиков плагинов. В стиле кулинарной книги. Много примеров. Много фрагментов кода. Разбито по сервисам (действия, i18n, маршрутизация, база данных и т.д.). Здесь следует обсуждать только публичный API и его поведение, а не детали реализации или обоснование.

design/*

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

contribute/*

Руководства для участников о различных способах участия в проекте.

appendix/*

Более подробная/мета/фоновая информация о проекте (история, дорожная карта и т.д.)

Используйте «Elgg» грамматически правильно

Elgg — это не акроним, поэтому написание его заглавными буквами (ELGG или E-LGG) неверно. Пожалуйста, не делайте этого.

В английском языке Elgg не требует артикля при использовании как существительное. Вот несколько примеров для подражания:

  • «I’m using Elgg to run my website»

  • «Install Elgg to get your community online»

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

  • «Go to the Elgg community website to get help.»

  • «I built an Elgg-based network yesterday»

Этот совет может не применяться в языках, отличных от английского.

Избегайте местоимений первого лица

Обращайтесь к читателю как к «вы». Не включайте себя в обычное повествование.

До:

Когда мы закончим установку Elgg, мы поищем несколько плагинов!

После:

Когда вы закончите установку Elgg, поищите несколько плагинов!

Чтобы сослаться на себя (избегайте этого, если возможно), используйте своё имя и пишите от третьего лица. Это проясняет будущим читателям/редакторам, чьё мнение выражается.

До:

Я думаю, что лучший способ сделать X — использовать Y.

После:

Эван считает, что лучший способ сделать X — использовать Y.

Устраняйте лишнее

До:

Если вы хотите использовать стороннюю библиотеку JavaScript в рамках фреймворка Elgg, вы должны позаботиться о вызове функции elgg_register_external_file для её регистрации.

После:

Чтобы использовать стороннюю библиотеку JavaScript, вызовите elgg_register_external_file для её регистрации.

Отдавайте предпочтение абсолютным датам перед относительными

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

До:

Недавно foo был запрещён. Вскоре baz тоже будет запрещён.

После:

Недавно (по состоянию на сентябрь 2013 года) foo был запрещён. Ожидается, что baz будет запрещён к октябрю 2013 года.

Не напоминайте читателю о вкладе

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

Интернационализация документации

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

cd docs/
make gettext

Для получения дополнительной информации см. http://www.sphinx-doc.org/en/stable/intl.html#translating-with-sphinx-intl

Особое внимание

При переводе документации обращайте внимание на специальный синтаксис в файлах документации.

НЕ переводите

  • Всё, что находится между символами вертикальной черты, не должно переводиться (например, master).

  • Код, если только это не комментарий в коде.