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

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

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

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

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

  1. Создайте Issue на SpongeDocs GitHub
  2. Создайте тему на форуме в категории SpongeDocs
  3. Посетите наш #spongedocs канал на irc.esper.net (требуется регистрация)

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

Изменения и дополнения к 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 forums or #spongedocs on irc.esper.net and ask for help there.

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. Программный код должен содержаться во встроенных литералах или блоках кода.
  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 — это живой документ, который всегда подлежит редактированию. Он никогда не будет идеальным, ему просто будет придана форма по мере необходимости.

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