Przewodnik redakcyjny

Przewodnik redakcyjny

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

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ń.

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 to process the text files and produce a multiple format output. It is recommended to take a look at SiSU's manual to get familiar with its markup, or else type:

 $ sisu --help markup  

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

- Dla pogrubienia użyj:

*{foo}* lub !{foo}!  

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

- Dla kursywy użyj:

/{foo}/  

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

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

#{foo}#  

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{

  $ foo
  # bar

 }code  

powoduje:

 $ foo
 # bar  

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.

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. W szczególności rozdział Tłumaczenie

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