Ogólne zasady redagowania artykułów

Podstawą rozbudowywania zawartości serwisu 4programmers.net (dalej w skrócie: "Serwis") jest ustalenie zasad i reguł, jakimi będziemy kierować się w trakcie pracy. Na tej stronie znajdują się reguły i wytyczne, którymi powinni kierować się autorzy artykułów w Kompendium.

Jako społeczność Serwisu nie możemy pozwolić sobie na samowolkę. Wyobraź sobie, iż każdy pisze artykuły stosując swój unikaly styl, używa formatowania, jakie jemu przypadło do gustu. Aby zapewnić odpowiedni poziom merytoryczny oraz techniczny Kompendium, musimy ustalić pewne zasady, według których będziemy rozbudowywać jego zawartość merytoryczną.

     1 Podstawowe reguły
          1.1 Formatowanie kodu
          1.2 Zmienne metasyntaktyczne
          1.3 Język
          1.4 Akapity
          1.5 Podział na rozdziały
          1.6 Styl
          1.7 Opinie
          1.8 Zwroty skierowane do czytelnika
          1.9 Brak podpisu
     2 Tworzenie stron
          2.10 Tworzenie nowych artykułów
          2.11 Wielkie i małe litery
          2.12 Niedozwolone znaki
     3 Linkowanie
     4 Sekcja "Zobacz też"
               4.12.1 Zobacz też
     5 Kategoryzacja

Podstawowe reguły

• Serwis jest wortalem poświęconym programowaniu komputerowemu; w Kompendium opisujemy więc tylko zagadnienia związane z komputerami i ich programowaniem.
• Serwis to nie Wikipedia. Nie umieszczaj linków ani stron wyjaśniających terminy takie jak: Microsoft, komputer, internet. Można natomiast umieszczać linki wskazujące na hasła takie jak Języki programowania czy Programowanie.
• Jeżeli modyfikujemy jakiś artykuł, dobrą praktyką jest dodawanie informacji o tym, co zmieniliśmy. Służy do tego pole "Opis zmian" znajdujące się w formularzu edycji artykułu.
• Niezalecane jest dublowanie treści znajdujących się w innym artykule, a już na pewno nieodpowiednie jest tworzenie dwóch artykułów o tej samej treści.
• Jeżeli opisujesz znaczenie słowa kluczowego (np. Unit), nie pisz referatu na temat modułów. Wystarczy krótka informacja, do czego służy to słowo kluczowe, notka o funkcjach modułu i jego budowie. Dołącz natomiast w tekście link, wraz z informacją, że więcej informacji na ten temat można znaleźć w artykule Moduły.
• Unikaj stosowania kolorów podczas formatowania tekstu. To, że dana strona dobrze wygląda w jednym schemacie kolorystycznym, nie oznacza, że tak samo dobrze będzie wyglądać w innych.
• Używaj mechanizmów formatowania opisanych na stronie Pomocy Formatowanie artykułów i komentarzy.
• Umieszczaj w artykule odnośniki do innych stron. Jak? Odpowiedź znajdziesz w artykule Formatowanie artykułów i komentarzy.
• Stosuj polskie znaki (ą, ę itd.)!
• Unikaj stosowania nadmiernej ilości kodu HTML; zamiast tego korzystaj z mechanizmów, które oferuje nasz system (patrz: Formatowanie artykułów i komentarzy).

Formatowanie kodu

To jest serwis o programowaniu komputerowym, więc często będziesz musiał wklejać fragmenty kodów źródłowych. Pisz czytelny kod! Stosuj wcięcia oraz styl wielbłądzi. Nikt nie chce czytać kodu zapisanego przykładowo w ten sposób:

var i:integer;
begin
for i:=0 to 10 do begin
writeln('Wyświetlono: ',i);
end;
end.

Zastanów się, czy nie lepiej prezentuje się kod zmodyfikowany i zaprezentowany poniżej?

var
  I : Integer;
begin
  for i := 0 to 10 do
  begin
    Writeln('Wyświetlono: ', i);
  end;
end.

Zmienne metasyntaktyczne

Opisując zagadnienia związane z programowaniem, często będziesz zmuszony prezentować przykłady działania danej funkcji. Nie musisz wówczas wymyślać logicznej nazwy programu, funkcji, modułu itp. Stosuj zmienne metasyntaktyczne! Są to na przykład zmienne o nazwach "Foo" lub "Bar":

program Foo;

var
  Bar : Word;
begin
  Bar := 10;
end;

Język

Unikaj stosowania potocznych pojęć czy żargonu; staraj się pisać poprawną polszczyzną, nie używaj uśmieszków – to nie miejsce na to. Przykładowy opis danego kodu zapisany przez użytkownika, z którego nie należy brać przykładu:

No trzeba tego no... o macie kod i wklejcie go do pliku dpr. jak dacie do OnCreate formy też bedzie dobrze . Aha jak wklejacie do dpr-a to dodajcie do uses windows!

Poziom takiej wypowiedzi jest żenujący. Pamiętaj! Opisując daną funkcję napisz parę zdań, do czego owa funkcja służy, czy też co może się stać, gdy podamy błędne parametry. Również publikując artykuł z kodem w działe Gotowce nie wklejaj do artykułu samego kodu! Napisz parę zdań tytułem wstępu, opisz, co dany kod robi, jakie komponenty są wymagane itp. (to samo tyczy się kategorii "FAQ"). Czy powyższy cytat nie wyglądałby lepiej (i bardziej profesjonalnie), gdyby był zapisany w innej formie? Na przykład:

W celu zapobiegania ponownemu uruchamianiu naszej aplikacji należy skorzystać z poniższego fragmentu kodu. Należy go użyć w pliku głównym – z rozszerzeniem *.dpr, aczkolwiek można go także wykorzystać w zdarzeniu OnCreate formularza. Proszę pamiętać o dodaniu do listy modułów (uses) modułu Windows.

Pamiętaj! Jeżeli coś robisz, zrób to raz a porządnie.

Akapity

Tekst artykułu wygląda czytelniej, jeżeli podzielony jest na akapity. Pierwsza linia akapitu nie musi posiadać wcięcia! Pamiętaj! Jeżeli zamieszczasz w Serwisie dłuższy artykuł, używaj znacznika {{CONTENT}}, który zostanie zamieniony na spis treści. Na samym początku artykułu napisz parę zdań tytułem wstępu, np. o czym artykuł będzie. Po pierwszym akapicie należy umieścić spis treści (czyli wspomniany znacznik {{CONTENT}}), a następnie rozwinięcie.

Podział na rozdziały

Aby artykuł był bardziej przejrzysty, należy stosować podział na rozdziały, podrozdziały i sekcje – szczególnie w przypadku większych artykułów. Możesz to uczynić zarówno przy pomocy znaczników HTML (<h1>, <h2> itd.), jak i przy pomocy języka Markdown (patrz: Formatowanie artykułów i komentarzy). Stosuj przy tym hierarchię sekcji: tekst dzielisz na sekcje główne, formatując je na przykład za pomocą znacznika <h1>; w takich sekcjach umieszczasz podrozdziały, formatując je na przykład za pomocą znaczników <h2> i <h3>.

Styl

Nie umieszczaj w artykule pytań retorycznych, czyli pytań w stylu: "Jak to zrobić?" czy "Ale co, gdy ta zmienna będzie miała wartość x?" Unikaj stosowania zwrotów takich jak "cześć", "witam", "pozdrawiam", "co słychać". Pamiętaj: to jest artykuł, a nie forum czy blog.

Ważne: unikaj pisania w pierwszej osobie liczby pojedynczej ("ja zrobiłem", "pisałem", "utworzyłem"). Pamiętaj, że artykuły w Serwisie mogą modyfikować wszyscy; jeśli zaś jeden artykuł ma wielu autorów, do kogo odnosi się pojęcie "ja"? Zamiast tego traktuj tekst, jakby był autorstwa Serwisu – całej społeczności. Możesz pisać przykładowo tak: "ostatnio zrobiliśmy", "przed chwilą pokazaliśmy", "utworzyliśmy" itp.

Nie rozkazuj czytelnikowi. Zamiast pisać: "Musisz kliknąć tutaj, a póżniej tam" (ew. "Kliknij tutaj, a potem tam"), pisz: "Aby to zrealizować, należy kliknąć tutaj, a następnie tam".

Opinie

Unikaj wyrażania opinii. Pamiętaj, że tekst mogą modyfikować wszyscy użytkownicy, a więc autorami danego tekstu może być więcej niż jedna osoba. Czyja opinia jest wówczas prezentowana? Zamiast pisać: "Według mnie lepszym rozwiązaniem…", pisz: "Być może lepszym rozwiązaniem będzie…"

Zwroty skierowane do czytelnika

Unikaj stosowania zwrotów w tylu: "Witam", "Pozdrawiam", "Cześć", "Dzień dobry". Są one odpowiednie w prywatnej korespondencji; wówczas są skierowane do konkretnej osoby. W artykułach nie stosujemy tego typu zwrotów.

Brak podpisu

Nie musisz podpisywać artykułu swoim nazwiskiem. Charakter Serwisu umożliwia modyfikację artykułów przez każdego zarejestrowanego użytkownika; mamy nadzieję, że dzięki temu artykuły i wskazówki będą posiadały lepszy poziom merytoryczny. Autorzy poszczególnych wersji danego artykułu są wypisani na stronie "Historia i autorzy" tego artykułu.

Tworzenie stron

Każdy zarejestrowany użytkownik może utworzyć stronę z artykułem. Jednak decyzja o jej utworzeniu powinna być przemyślana, a szczególnie wybór kategorii, do której ta strona ma należeć. Zadecydowanie zabronione jest tworzenie stron bez kategorii, a które opisują zagadnienia danego języka – o adresie np. http://4programmers.net/MessageBox. Prawidłowy adres do takiej strony (uwzględniający odpowiednią kategorię) powinien wyglądać tak: Messagebox.

Tworzenie nowych artykułów

Zobacz: Tworzenie i edycja artykułów i komentarzy

Wielkie i małe litery

System nie rozróżnia małych i wielkich liter, więc nieistotne jest, jak zapisany został tytuł artykułu. Domyślnie pierwsza litera tekstu danego artykułu jest przekształcana na wielką. Zalecamy pisanie tekstów artykułów małymi literami.

W przypadku języka Delphi w nazwach zmiennych stosujemy styl "wielbłądzi" ("MessageBox", "ShowMessage"). Proszę pamiętać o zapisie nazw klas charakterystycznych dla Delphi – dwie pierwsze litery powinny być wielkie (np. TForm, TMainMenu).

W przypadku języka PHP czy C/C++ większość programistów pisze nazwy funkcji i słowa kluczowe małą literą. My także prosimy o dostosowanie się do tej reguły.

Niedozwolone znaki

Istnieją pewne restrykcje w nazewnictwie stron. Co prawda ogónie rzecz biorąc tytuł strony może zawierać znaki zapisane w kodowaniu UTF-8, lecz następujące znaki są usuwane przez oprogramowanie: ' " | ? & \\ # $ ^ =. Spacje są automatycznie zastępowane przez znaki podkreślenia (_).

Linkowanie

Odnośniki są bardzo ważnym elementem tworzonych artykułów. Odnośniki należy tworzyć w celu odwołania się do innych artykułów. Informacje odnośnie tworzenia odnośników znajdziesz na stronie: Formatowanie artykułów i komentarzy.

(TODO) Jeżeli w tytule artykułu znajdują się spacje, nie trzeba w trakcie tworzenia linków używać znaku podkreślenia.

Przydatne jest tworzenie linków do artykułów już obecnych w Serwisie. Pozwala to użytkownikowi na łatwiejszą nawigację pomiędzy artykułami.

Sekcja "Zobacz też"

Bardzo dobrą praktyką jest umieszczanie na końcu danego artykułu odnośników do innych artykułów, które mogą być powiązane tematycznie, czy też zawierają więcej informacji na dany temat. Oto jak może wyglądać sekcja z linkami:

Zobacz też

• Pomoc
• Formatowanie artykułów i komentarzy

Wypunktowanie, tak jak w powyższym przykładzie, tworzymy na przykład przy pomocy znaku gwiazdki (*). Zobacz: Formatowanie artykułów i komentarzy, aby dowiedzieć się więcej.

Kategoryzacja

Kategorie pozwalają zorientować się w ogólnej strukturze Kompendium, a także w nawigacji po stronie. Dobrze jest więc kategoryzować dany artykuł w grupy tematyczne. Przykładowo słowa kluczowe języka Delphi tworzymy w kategorii Delphi, tak więc wszystkie strony opisujące słowa kluczowe znajdują się pod adresem http://4programmers.net/Delphi/(Nazwa tekstu). Na przykład String – artykuł String opisuje typ danych języka Delphi o nazwie String. Warto jest więc zebrać wszystkie typy języka w jedną całość i (dodać do kategorii – Typy danych – TODO A nie po prostu utworzyć taki artykuł?). W takim wypadku użytkownik, który odwiedzi stronę Typy danych, będzie miał podane "na talerzu" wszystkie typy języka Delphi.

Więcej! Typ String należy do typów łańcuchowych, więc można (dodać ten artykuł także do kategorii Łańcuchowe, której kategorią macierzystą jest "Typy danych" – TODO Jak można dodawać artykuł do wielu kategorii?). Mamy więc artykuł "String", który może należeć do trzech kategorii: "Delphi", "Typy danych", "Łańcuchowe".

Jak przypisywać dany artykuł do wielu kategorii? Przeczytaj artykuł: Kategoryzowanie.