Live manual Debian Live

# Debian Live Manual

# Przewodnik redakcyjny

861

# 17. Przewodnik redakcyjny

862

17.1 Wytyczne dla autorów

863

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.

864

Uwaga: Autorzy powinni najpierw przeczytać Współtworzenie tego dokumentu

865

17.1.1 Funkcje językowe

866

- Użyj zwykłego angielskiego

867

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

868

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.

869

- Różnorodność języka angielskiego

870

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.

871

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

872

- Bądź zbalansowany

873

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.

874

- Bądź poprawny politycznie

875

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.

876

- Bądz zwięzły

877

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.

878

- Oszczędź pracy tłumaczącym

879

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.

880

- Bądź zgodny

881

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.

882

- Be spójny

883

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

884

- Bądź opisowy

885

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.

886

- Słownik

887

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.

888

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.

889

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.

890

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

891

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.

892

- Fałszywi przyjaciele, idiomy i inne wyrażenia idiomatyczne

893

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.

894

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!

895

- Unikaj slangu, skrótów, mowy potocznej...

896

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

897

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

898

17.1.2 Procedury

899

- Przetestuj przed zapisaniem

900

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.

901

- Przykłady

902

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

903

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.

904

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.

905

- Linki zewnętrzne

906

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.

907

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

908

- Unikaj nadawania marki i rzeczy, które naruszają licencję zgodnie z którą podręcznik ten został opublikowany

909

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.

910

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.

911

- Napisz pierwszy szkic, przeglądnij go, edytuj, popraw i cofnij zmiany jeżeli wymaga tego sytuacja

912

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

913

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

914

- Dokonaj przeglądu gramatyki, składni i pisowni. Należy pamiętać, że właściwe nazwy wydań, takich jak buster 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`

915

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

916

- Rozdziały

917

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.

918

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.

919

- Znaczniki

920

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:

921

$ sisu --help markup

922

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

923

- Dla pogrubienia użyj:

924

*{foo}* lub !{foo}!

925

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

926

- Dla kursywy użyj:

927

/{foo}/

928

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

929

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

930

#{foo}#

931

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

932

- Dla bloków z kodem użyj:

933

code{
$ foo
# bar
}code

934

powoduje:

935

$ foo
# bar

936

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.

937

17.2 Wytyczne dla tłumaczy

938

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

939

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.

940

Uwaga: Tłumacze powinni również przeczytać Współtworzenie tego dokumentu. W szczególności rozdział Tłumaczenie

941

17.2.1 Wskazówki tłumaczenia

942

- Komentarze

943

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.

944

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.

945

- UT, Uwagi Tłumacza

946

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

947

- Wyrażenia w trybie bezosobowym

948

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.

949

- Fałszywi przyjaciele

950

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.

951

- Znaczniki

952

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.

953

- Bloki kodowe

954

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.

955

- Nowe linijki

956

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.

957

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.

958

- Nieprzetłumaczalne ciągi znaków

959

Tłumacze nigdy nie powinni tłumaczyć:

960

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

961

- Nazw programów

962

- Komend podanych jako przykład

963

- Metadanych (zazwyczaj pomiędzy dwukropkami :metadata:)

964

- Linków

965

- Ścieżek dostępnowych