path: root/markup/pod/live-manual/media/text/pl/appendix_style-guide.ssi

:B~ Przewodnik redakcyjny

1~style-guide Przewodnik redakcyjny

2~ Wytyczne dla autorów

Ten rozdział zajmuje się pewnymi ogólnymi rozważaniami, które należy wziąć
pod uwagę podczas pisania dokumentacji technicznej dla live-instrukcji. Są
one podzielone na funkcje językowe oraz zalecane procedury.

*{Uwaga:}* Autorzy powinni najpierw przeczytać {Współtworzenie tego dokumentu}#how-to-contribute

3~ Funkcje językowe

_* /{Użyj zwykłego angielskiego}/

Należy pamiętać, że wysoki procent czytelników nie są rodzimymi
użytkownikami języka angielskiego. Więc jako generalną zasadę spróbuj używać
krótkich, sensownych zdań, zakończonych kropką.

To nie znaczy, że trzeba korzystać z uproszczonego, naiwnego
stylu. Proponuje się unikać, na ile to możliwe, złożonych zdań podrzędnych,
które czynią tekst trudny do zrozumienia dla nie rodzimych użytkowników
języka angielskiego.

_* /{Różnorodność języka angielskiego}/

The most widely spread varieties of English are British and American so it
is very likely that most authors will use either one or the other. In a
collaborative environment, the ideal variety would be "International
English" but it is very difficult, not to say impossible, to decide on which
variety among all the existing ones, is the best to use.

Spodziewamy się, że różne odmiany języka mogą mieszać się bez tworzenia
nieporozumień, ale ogólnie należy starać się być spójnym i przed podjęciem
decyzji o użyciu brytyjskiego, amerykańskiego lub innego dialektu języka
angielskiego wedle uznania, proszę przyjrzeć się, jak inni ludzie piszą i
postarać się ich naśladować.

_* /{Bądź zbalansowany}/

Nie być stronniczy. Unikaj w tym odniesienia do ideologii zupełnie
niepowiązanych z live-manual. Pismo techniczne powinny być możliwie jak
najbardziej neutralne. Jak to jest w naturze piśmiennictwa naukowego.

_* /{Bądź poprawny politycznie}/

Staraj się unikać seksistowskiego języka, jak to jest tylko możliwe. Jeśli
potrzebujesz, odwołania do trzeciej osoby liczby pojedynczej najlepiej użyć
jakiejś formy bezosobowej lub "wy" zamiast "on" , "ona" lub niewygodnych
wynalazków, takie jak "mógłbyś/mogłabyś", "byłem/łam"  i podobnych.

_* /{Bądz zwięzły}/

Go straight to the point and do not wander around aimlessly. Give as much
information as necessary but do not give more information than necessary,
this is to say, do not explain unnecessary details. Your readers are
intelligent. Presume some previous knowledge on their part.

_* /{Oszczędź pracy tłumaczącym}/

Należy pamiętać, że cokolwiek napiszesz będzie musiało zostać przetłumaczone
na kilka innych języków. Oznacza to, że sporo osób, będzie musiał wykonać
dodatkową pracę jeśli dodasz bezużyteczne lub nadmiarowe informacje.

_* /{Bądź zgodny}/

As suggested before, it is almost impossible to standardize a collaborative
document into a perfectly unified whole. However, every effort on your side
to write in a coherent way with the rest of the authors will be appreciated.

_* /{Be spójny}/

Use as many text-forming devices as necessary to make your text cohesive and
unambiguous. (Text-forming devices are linguistic markers such as
connectors).

_* /{Bądź opisowy}/

It is preferable to describe the point in one or several paragraphs than
merely using a number of sentences in a typical "changelog" style. Describe
it! Your readers will appreciate it.

_* /{Słownik}/

Look up the meaning of words in a dictionary or encyclopedia if you do not
know how to express certain concepts in English. But keep in mind that a
dictionary can either be your best friend or can turn into your worst enemy
if you do not know how to use it correctly.

English has the largest vocabulary that exists (with over one million
words). Many of these words are borrowings from other languages. When
looking up the meaning of words in a bilingual dictionary the tendency of a
non-native speaker of English is to choose the one that sounds more similar
in their mother tongue. This often turns into an excessively formal
discourse which does not sound quite natural in English.

Zgodnie z ogólną zasadą, jeśli koncepcja może być wyrażony za pomocą różnych
synonimów to dobrą radą będzie wybieranie pierwszego słowa zaproponowanego
przez słownik. W razie wątpliwości, często słusznym jest wybieranie słowa
pochodzenia germańskiego (zwykle jednosylabowe słowa). Ostrzegamy, że te
dwie techniki, mogą produkować raczej mowę nieformalną, ale przynajmniej
wybór słów będzie o szerokim zastosowaniu i ogólnie przyjęty.

Korzystanie ze słownika kolokacji jest zalecane. Są one bardzo pomocne,
kiedy przychodzi do znajomości słów najczęściej występujących razem.

Ponownie; dobrą praktyką jest, aby uczyć się z pracy innych. Korzystanie z
wyszukiwarki, aby sprawdzić, jak inni autorzy mogą korzystać z niektórych
wyrażeń może bardzo pomóc.

_* /{Fałszywi przyjaciele, idiomy i inne wyrażenia idiomatyczne}/ 

Uważaj na fałszywych przyjaciół. Bez względu na to, jak biegły jesteś w
obcym języku nie można pomóc wpadając od czasu do czasu w pułapkę tzw.
"fałszywych przyjaciół", słowa, które wyglądają podobnie w dwóch językach,
ale których znaczenie lub zastosowanie może być zupełnie inne.

Staraj się unikać idiomów w jak największym stopniu. "Idiomy" to wyrażenia,
które mogą mieć znaczenie zupełnie odmienne od tego, co ich poszczególne
słowa wydają się oznaczać. Czasami, idiomy, mogą być trudne do zrozumienia
nawet dla rodzimych użytkowników języka angielskiego!

_* /{Unikaj slangu, skrótów, mowy potocznej...}/

Nawet jeśli popierasz korzystanie ze zwykłego, codziennego języka
angielskiego, pisanie techniczne należy do formalnej formy języka.

Staraj się unikać slangu, niepopularnych skrótów, które są trudne do
zrozumienia, a przede wszystkim skrótów, które próbują naśladować język
mówiony. Nie wspominając o typowych dla kanałów IRC i przyjaznych dla
zamkniętych gron wyrażeń.

3~ Procedury

_* /{Przetestuj przed zapisaniem}/

It is important that authors test their examples before adding them to
live-manual to ensure that everything works as described. Testing on a clean
chroot or VM can be a good starting point. Besides, it would be ideal if the
tests were then carried out on different machines with different hardware to
spot possible problems that may arise.

_* /{Przykłady}/

W przypadku dostarczania przykładu spróbuj być tak dokładny jak tylko
możesz. Przykład jest, mimo wszystko, tylko przykładem.

It is often better to use a line that only applies to a specific case than
using abstractions that may confuse your readers. In this case you can
provide a brief explanation of the effects of the proposed example.

There may be some exceptions when the example suggests using some
potentially dangerous commands that, if misused, may cause data loss or
other similar undesirable effects. In this case you should provide a
thorough explanation of the possible side effects.

_* /{Linki zewnętrzne}/

Links to external sites should only be used when the information on those
sites is crucial when it comes to understanding a special point. Even so,
try to use links to external sites as sparsely as possible. Internet links
are likely to change from time to time resulting in broken links and leaving
your arguments in an incomplete state.

Poza tym, ludzie, którzy czytają instrukcję w trybie offline nie będą mogli
śledzić tych linków.

_* /{Unikaj nadawania marki i rzeczy, które naruszają licencję zgodnie z
którą podręcznik ten został opublikowany}/

Try to avoid branding as much as possible. Keep in mind that other
downstream projects might make use of the documentation you write. So you
are complicating things for them if you add certain specific material.

live-manual jest oparty na licencji GNU GPL. Ma to wiele skutków, które
odnoszą się do redystrybucji materiału (dowolnego rodzaju, w tym grafiki
chronionej prawami autorskimi lub logo), który jest opublikowany wraz nim.

_* /{Napisz pierwszy szkic, przeglądnij go, edytuj, popraw i cofnij zmiany
jeżeli wymaga tego sytuacja}/

 - Burza mózgów!. Najpierw musisz zorganizować swoje pomysły w logicznej
   kolejności zdarzeń.

 - Kiedy już w jakiś sposób masz zorganizowane te koncepcje w głowie napisz
   pierwszy szkic.

 - Dokonaj przeglądu gramatyki, składni i pisowni. Należy pamiętać, że
   właściwe nazwy wydań, takich jak ${testing} lub sid nie powinny być
   kapitalizowane, gdy odnosi się do nich jako nazw kodowych. Aby sprawdzić
   pisownię można uruchomić cel "spell". tj. polecenie #{make spell}#

 - Udoskonalaj swoje wyrażenia, a jeśli to konieczne cofnij i przerób każdą
   część.

_* /{Rozdziały}/

Use the conventional numbering system for chapters and subtitles. e.g. 1,
1.1, 1.1.1, 1.1.2 ... 1.2, 1.2.1, 1.2.2 ... 2, 2.1 ... and so on. See markup
below.

If you have to enumerate a series of steps or stages in your description,
you can also use ordinal numbers: First, second, third ... or First, Then,
After that, Finally ... Alternatively you can use bulleted items.

_* /{Znaczniki}/

And last but not least, live-manual uses {SiSU}http://www.sisudoc.org/ to
process the text files and produce a multiple format output. It is
recommended to take a look at {SiSU's
manual}http://www.sisudoc.org/sisu/en/html/sisu_manual/markup.html to get
familiar with its markup, or else type:

code{

 $ sisu --help markup

}code

To są przykłady znaczników, które mogą okazać się użyteczne:

 - Dla pogrubienia użyj:

code{

*{foo}* lub !{foo}!

}code

powoduje: *{foo}* lub !{foo}!. Użyj tego by wyszczególnić określone słowa
kluczowe.

 - Dla kursywy użyj:

code{

/{foo}/

}code

powoduje: /{foo}/.  Użyj tego dla np. nazw paczek Debiana.

 - Dla czcionki o stałej szerokości użyj:

code{

#{foo}#

}code

powoduje: #{foo}#. Użyj tego np. dla nazw poleceń. A także aby uwidocznić
poszczególne słowa kluczowe jak ścieżki dostępowe.

 - Dla bloków z kodem użyj:

code{

 code{

  $ foo
  # bar

 }code

}code

powoduje:

code{

 $ foo
 # bar

}code

Użyj #{code{}# do otwarcia i #{}code# do zamknięcia tagu. Ważne jest, aby
pamiętać, by zostawić miejsce na początku każdej linii kodu.

2~guidelines-translators Wytyczne dla tłumaczy

Ta sekcja zajmuje się pewnymi ogólnymi rozważaniami, które należy wziąć pod
uwagę przy tłumaczeniu zawartości live-manual.

Jako ogólne zalecenie, tłumacze powinni przeczytać i zrozumieć zasady
tłumaczenia, które mają zastosowanie do ich specyficznych
języków. Zazwyczaj, grupy i listy dyskusyjne tłumaczeń dostarczają
informacji o tym, jak tworzyć przetłumaczone pracę zgodne z normami jakości
Debiana.

*{Uwaga:}* Tłumacze powinni również przeczytać {Współtworzenie tego dokumentu}#how-to-contribute. W szczególności rozdział {Tłumaczenie}#translation

3~ Wskazówki tłumaczenia

_* /{Komentarze}/

The role of the translator is to convey as faithfully as possible the
meaning of words, sentences, paragraphs and texts as written by the original
authors into their target language.

So they should refrain from adding personal comments or extra bits of
information of their own. If they want to add a comment for other
translators working on the same documents, they can leave it in the space
reserved for that. That is, the header of the strings in the *{po}* files
preceded by a number sign *{#}*. Most graphical translation programs can
automatically handle those types of comments.

_* /{UT, Uwagi Tłumacza}/

It is perfectly acceptable however, to include a word or an expression in
brackets in the translated text if, and only if, that makes the meaning of a
difficult word or expression clearer to the reader. Inside the brackets the
translator should make evident that the addition was theirs using the
abbreviation "TN" or "Translator's Note".

_* /{Wyrażenia w trybie bezosobowym}/

Documents written in English make an extensive use of the impersonal form
"you". In some other languages that do not share this characteristic, this
might give the false impression that the original texts are directly
addressing the reader when they are actually not doing so. Translators must
be aware of that fact and reflect it in their language as accurately as
possible.

_* /{Fałszywi przyjaciele}/

Pułapka "fałszywych przyjaciół" wyjaśnionych wcześniej szczególnie dotyczy
tłumaczy. Dwukrotnie sprawdzić znaczenie podejrzanych fałszywych przyjaciół
w razie wątpliwości.

_* /{Znaczniki}/

Tłumacze pracujący początkowo nad plikami *{pot}*, a później z plikami *{po}
* znajdą wiele znaczników w ciągach. Mogą oni przetłumaczyć tekst tak, jak
to jest tylko możliwe do tłumaczenia, ale niezwykle ważnym jest, aby używali
oni dokładnie takich samych znaczników jak w oryginalnej wersji angielskiej.

_* /{Bloki kodowe}/

Mimo, że bloki z kodem są zazwyczaj nieprzetłumaczalne, zawarcie ich w
tłumaczeniach jest jedynym sposobem, aby zdobyć 100% kompletne
tłumaczenie. I mimo, że oznacza to więcej pracy na początku, bo to może
wymagać interwencji od tłumaczy jeśli kod się zmieni, to jest to najlepszy
sposób, w dłuższej perspektywie czasu na określenie, co już zostało
przetłumaczone, a co nie podczas sprawdzania integralności plików .po.

_* /{Nowe linijki}/

Przetłumaczone teksty muszą mieć te same znaki nowej linii jak teksty
oryginalne. Należy uważać, aby nacisnąć klawisz "Enter" lub wpisać *{\n}*
jeśli pojawią się one w oryginalnych plików. Znaki te często pojawiają się,
na przykład, w blokach z kodem.

Nie popełniaj błedów, to nie znaczy, że przetłumaczony tekst musi mieć taką
samą długość jak w wersji angielskiej. Jest to prawie niemożliwe.

_* /{Nieprzetłumaczalne ciągi znaków}/

Tłumacze nigdy nie powinni tłumaczyć:

 - Nazw kodowych wydań (które powinny być pisane małymi literami)

 - Nazw programów

 - Komend podanych jako przykład

 - Metadanych (zazwyczaj pomiędzy dwukropkami *{:metadata:}*)

 - Linków

 - Ścieżek dostępnowych