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

Предупреждение

This documentation refers to an outdated SpongeAPI version and is no longer actively maintained. While the code examples still work for that API version, the policies, guidelines, and some links may have changed. Please refer to the latest version of the documentation for those.

Документация Sponge, по-другому «SpongeDocs», — официальная документация проекта Sponge. Преследуемые цели SpongeDocs:

  • Помощь пользователям в настройке сервера Sponge.

  • Предоставление разработчикам информации о том, как помочь проекту Sponge.

  • Предоставление разработчикам информации о том, как начать разработку плагинов.

Сообщение о проблемах

Всегда может случиться так, что страница устаревает, появляется ошибка или вы просто смотрите страницу и думаете: «Это же можно объяснить проще!». Если это так, и вы по какой-то причине не можете самостоятельно исправить ошибку, есть три способа сообщить нам о проблеме:

  1. Создайте Issue на SpongeDocs GitHub

  2. Создайте тему на форуме в категории SpongeDocs

  3. Посетите наш #spongedocs канал на irc.esper.net (требуется регистрация)

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

Изменения и дополнения к SpongeDocs следует отправлять как PR в репозиторий SpongeDocs на GitHub. Мы не требуем, чтобы он был идеальным сразу, поскольку в процессе рецензирования часто требуется уточнение PR. Неполные объяснения также приветствуются, поэтому не стесняйтесь, если есть моменты, которые вы не понимаете. Всегда найдется кто-то, кто сможет заполнить пробелы.

Документация пишется в reStructuredText (reST), если вы знакомы с Markdown (md), шаг к reST не должен быть сложным. Если у вас есть проблемы с ним, мы рекомендуем присоединиться к нашим форумам или`#SpongeDocs <ircs://irc.esper.net:6697/#spongedocs>`_ на Esper.net и попросить помощи там.

The Sponge Documentation is licensed under the Creative Commons - Share-Alike license. Art assets are held under the related Creative Commons - Non Commercial, No Derivatives license. Contributions implicitly accept this licensing.

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

Чтобы убедиться, что у нас есть согласованный формат на всех страницах SpongeDocs, вот рекомендации, которые мы разработали для написания документации Sponge. Этот список может быть дополнен (или изменён) по мере увеличения объёма документации.

  1. Заголовки должны быть написаны С Большой Буквы (<- пример) [для переводов см. #8].

  2. Заголовки страниц должны иметь смысл (заголовок отображается как ссылка).

  3. Программный код должен содержаться во встроенных литералах или блоках кода.

  1. Постарайтесь не помещать слишком много текста в блоки кода, так как они не переводятся. Соавторам рекомендуется, по возможности, не комментировать блоки кода. В некоторых примерах может потребоваться простой place-holder текст. В идеале, примеры блоков кода должны быть короткими и сопровождаться объяснением для каждого примера в виде текста. Конечно, могут быть некоторые концепции, которые не могут быть проиллюстрированы кратким примером.

  1. Разделяйте области для Пользователей, Разработчиков плагинов и Разработчиков Sponge.

  2. Избегайте повторения, разделяя страницы, где это возможно.

  3. Оставляйте ссылки на внешние ресурсы, а не воспроизводите их.

  1. Некоторые исключения сделаны для целей перевода.

  1. Установите различие между SpongeForge, SpongeVanilla и SpongeAPI.

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

  3. Sponge — это название проекта и оно НЕ переводится.

  1. Некоторые языки могут также использовать и фонетический перевод.

  1. Машинные переводы (прим., Microsoft Translator) настоятельно не рекомендуется использовать. Они часто содержат серьезные ошибки и, скорее всего, будут отклонены.

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

  3. Символы кода должны быть заглавными в их первоначальной форме и не иметь лишних пробелов (прим., blockState (имя поля) или BlockState (имя класса), а не block state). Они также должны быть форматированы как литералы, используя двойные обратные кавычки (прим., blockState) в тексте.

  4. Длина строк должна быть не более 120 символов.

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

Примечание

Поскольку Sponge все еще находится в постоянном движении, ожидается дефицит документации по разработке. До официального выпуска Sponge, обязательно найдутся пустоты по многим предметам. Тем не менее, SpongeDocs — это живой документ, который всегда подлежит редактированию. Он никогда не будет идеальным, ему просто будет придана форма по мере необходимости.

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