Rozwijanie SpongeDocs

Ostrzeżenie

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.

Dokumentacja Sponge, zwana również „SpongeDocs” jest oficjalną dokumentacją projektu Sponge. Celem SpongeDocs jest:

  • Pomoc użytkownikom w przygotowaniu ich własnych serwerów opartych na implementacji Sponge.

  • Dostarczenie deweloperom informacji w jaki sposób mogą przyczynić się do rozwoju projektu Sponge.

  • Dostarczanie deweloperom informacji jak rozpocząć tworzenie własnych pluginów.

Zgłaszanie problemów

Zawsze może zdarzyć się, że strony są nieaktualne, pojawiają się błędy lub po prostu patrzysz na stronę i myślisz „Jest lepszy sposób na wyjaśnienie tego.” Jeśli tak jest z jakiegoś powodu to istnieją trzy sposoby uświadamiania nas o tym problemie:

  1. Tworzenie Zgłoszenie na SpongeDocs GitHub

  2. Stworzenie Wątku na Kategoria Forum SpongeDocs

  3. Odwiedź nasz kanał #spongedocs na irc.esper.net (musisz być zarejestrowany)

Pisanie dokumentów

Zmiany i uzupełnienia do SpongeDocs powinny być wysyłane jako Pull Request do repozytorium SpongeDocs na GitHub. Nie wymagamy perfekcji od przesyłanych dokumentów, zawsze można delikatnie poprawić w procesie przeglądu. Niekompletne wyjaśnienia są również mile widziane, jeśli istnieją pewne części, których nie rozumiesz. Zawsze będzie ktoś, kto może wypełnić luki.

Dokumenty są napisane w reStructuredText (reST), jeśli jesteś zaznajomiony z Markdown (md) to pisanie reST nie powinno być trudne. Jeżeli masz problemy z nim to sugerujemy, abyś dołączył do naszego forum lub kanału IRC #SpongeDocs <irc://irc.esper.net:6667/spongedocs> na Esper.net i poprosić tam o pomoc.

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.

Estetyka Pisania

Aby upewnić się, że mamy wspólny format na wszystkich stronach SpongeDocs, tutaj znajdują się wskazówki, które stworzyliśmy do pisania dokumentacji Sponge. Ta lista może się zwiększyć (lub zmniejszyć) gdy dokumenty Sponge staną się większe.

  1. Nagłówki Powinny Być Napisane Wielką Literą (<– przykład)

  2. Nagłówki stron powinny być sensowne (nagłówek pojawi się jako link).

  3. Kod programu powinien być zawarty w zgodnych literałach lub blokach kodowych.

  1. Staraj się nie umieszczać zbyt dużo tekstu w blokach kodowych, ponieważ nie mogą być tłumaczone. Współtwórcy są zniechęceni do zmiany z bloków kodowych na krótkie teksty. Proste symbole zastępcze mogą być konieczne w niektórych przykładach. Idealny przykład w bloku kodowy będzie krótki, a następnie wyjaśniony w tekście. Oczywiście mogą istnieć pewne pojęcia, które nie mogą być ilustrowane przez krótki przykład.

  1. Zachowaj odrębne obszary dla Użytkowników, Twórców Pluginów i Deweloperów Sponge.

  2. Należy unikać powtarzania, poprzez zapożyczanie stron, gdy jest to możliwe.

  3. Twórz łącze do zasobów zewnętrznych, zamiast ich przepisywać.

  1. Niektóre wyjątki, są tworzone do celów tłumaczeń.

  1. Twórz rozróżnienia między SpongeForge, SpongeVanilla i SpongeAPI.

  2. Jeżeli wygląda to okropnie w twoim języku, stwórz własne zasady.

  3. Sponge jest nazwą projektu i NIE powinno być tłumaczone.

  1. Niektóre języki mogą chcieć skorzystać także z tłumaczenia fonetycznego.

  1. Automatyczne tłumaczenia (np.: Google Translate) są odradzane. Te często zawierają poważne błędy i będą prawdopodobnie odrzucone.

  2. Tytuły i nagłówki sekcji powinne być zwykłym tekstem, unikaj bloków liter i innych formatowań.

  3. Symbole kodu powinno zachować wielkość liter w ich oryginalnej formie i nie mieć dodatkowych spacji (np. blockState (pole nazwa) lub BlockState (nazwa klasy), a nie block state). Również powinien być sformatowany kodem za pomocą podwójnie lewym apostrofem (np.: blockState) w tekście.

  4. Linie powinny mieć maksymalną długość do 120 znaków.

  5. Importy powinny być rozpisane w blokach kodowych jako pierwsze, że są one w każdym artykule ale nie powtórzone po raz pierwszy.

Informacja

Jako to, że Sponge jest nadal w stanie tworzenia, możemy się spodziewać niedoboru dokumentów, aż do oficjalnego wydania Sponge. Na pewno będą pustki w wielu dziedzinach. Niemniej jednak SpongeDocs jest żyjącym dokumentem i zawsze podlega edycji. Nigdy nie będzie doskonały, jedynie dobity do kształtu takiego jaki jest potrzebny.

Dodatki, sugestie i korekty są zawsze mile widziane.