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

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

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

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

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

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

It may always occur that a page gets outdated, an error sneaks in or you just look at a page and think «Well, there is a better way of explaining this.» If that is the case and you are for some reason not able to provide a fix yourself, there are four ways of making us aware of the problem:

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

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

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

  4. Visit us on our Discord Server, namely the #docs channel.

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

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

The Docs are written in reStructuredText (reST), if you’re familiar with Markdown (md) the step to reST shouldn’t be too hard. If you’re having issues with it we suggest that you join our #spongedocs on irc.esper.net and ask for help there, or join our Discord Server and post on the #docs channel. Discord and IRC are linked, so you’ll get the same support irrespective of the platform you choose. Alternatively, you can post on our forums if you think it is more apropriate.

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. Contributors implicitly accept this licensing.

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

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

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

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

  3. Program code should be contained in inline literals or code blocks.

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

  2. Use the following code block types for particular code blocks:

  • Groovy/Gradle-Files -> groovy

  • Hocon-Config -> guess (hocon highlighting is not yet supported)

  • In-Game/Server Console Command -> none

  • Java-Code -> java

  • Json-Config -> json

  • Linux-Terminal -> bash

  • Logs -> none

  • Text -> text

  • Windows-Console -> bat

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

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

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

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

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

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

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

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

  1. Automated translations (e.g. Google Translate) are strongly discouraged. These often contain serious errors, and are very likely to be rejected.

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

  3. Code symbols should be capitalized in their original form and have no extra spaces (e.g. blockState (a field name) or BlockState (a class name), rather than block state). They should also be formatted as a literal using double backticks (e.g. blockState) in body text.

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

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

Примечание

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

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