diff options
Diffstat (limited to 'markup/pod/live-manual/media/text/ro/appendix_style-guide.ssi')
| -rw-r--r-- | markup/pod/live-manual/media/text/ro/appendix_style-guide.ssi | 364 |
1 files changed, 364 insertions, 0 deletions
diff --git a/markup/pod/live-manual/media/text/ro/appendix_style-guide.ssi b/markup/pod/live-manual/media/text/ro/appendix_style-guide.ssi new file mode 100644 index 0000000..1bba13e --- /dev/null +++ b/markup/pod/live-manual/media/text/ro/appendix_style-guide.ssi @@ -0,0 +1,364 @@ +:B~ Style guide + +1~style-guide Style guide + +2~ Guidelines for authors + +This section deals with some general considerations to be taken into account +when writing technical documentation for live-manual. They are divided into +linguistic features and recommended procedures. + +*{Note:}* Authors should first read {Contributing to this document}#how-to-contribute + +3~ Linguistic features + +_* /{Use plain English}/ + +Keep in mind that a high percentage of your readers are not native speakers +of English. So as a general rule try to use short, meaningful sentences, +followed by a full stop. + +This does not mean that you have to use a simplistic, naive style. It is a +suggestion to try to avoid, as much as possible, complex subordinate +sentences that make the text difficult to understand for non-native speakers +of English. + +_* /{Variety of English}/ + +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. + +We expect that different varieties may mix without creating +misunderstandings but in general terms you should try to be coherent and +before deciding on using British, American or any other English flavour at +your discretion, please take a look at how other people write and try to +imitate them. + +_* /{Be balanced}/ + +Do not be biased. Avoid including references to ideologies completely +unrelated to live-manual. Technical writing should be as neutral as +possible. It is in the very nature of scientific writing. + +_* /{Be politically correct}/ + +Try to avoid sexist language as much as possible. If you need to make +references to the third person singular preferably use "they" rather than +"he" or "she" or awkward inventions such as "s/he", "s(he)" and the like. + +_* /{Be concise}/ + +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. + +_* /{Minimize translation work}/ + +Keep in mind that whatever you write will have to be translated into several +other languages. This implies that a number of people will have to do an +extra work if you add useless or redundant information. + +_* /{Be coherent}/ + +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 cohesive}/ + +Use as many text-forming devices as necessary to make your text cohesive and +unambiguous. (Text-forming devices are linguistic markers such as +connectors). + +_* /{Be descriptive}/ + +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. + +_* /{Dictionary}/ + +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. + +As a general rule, if a concept can be expressed using different synonyms, +it is a good advice to choose the first word proposed by the dictionary. If +in doubt, choosing words of Germanic origin (Usually monosyllabic words) is +often the right thing to do. Be warned that these two techniques might +produce a rather informal discourse but at least your choice of words will +be of wide use and generally accepted. + +Using a dictionary of collocations is recommended. They are extremely +helpful when it comes to know which words usually occur together. + +Again it is a good practice to learn from the work of others. Using a search +engine to check how other authors use certain expressions may help a lot. + +_* /{False friends, idioms and other idiomatic expressions}/ + +Watch out for false friends. No matter how proficient you are in a foreign +language you cannot help falling from time to time in the trap of the so +called "false friends", words that look similar in two languages but whose +meanings or uses might be completely different. + +Try to avoid idioms as much as possible. "Idioms" are expressions that may +convey a completely different meaning from what their individual words seem +to mean. Sometimes, idioms might be difficult to understand even for native +speakers of English! + +_* /{Avoid slang, abbreviations, contractions...}/ + +Even though you are encouraged to use plain, everyday English, technical +writing belongs to the formal register of the language. + +Try to avoid slang, unusual abbreviations that are difficult to understand +and above all contractions that try to imitate the spoken language. Not to +mention typical irc and family friendly expressions. + +3~ Procedures + +_* /{Test before write}/ + +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. + +_* /{Examples}/ + +When providing an example try to be as specific as you can. An example is, +after all, just an example. + +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. + +_* /{External links}/ + +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. + +Besides, people who read the manual offline will not have the chance to +follow those links. + +_* /{Avoid branding and things that violate the license under which the +manual is published}/ + +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 is licensed under the GNU GPL. This has a number of implications +that apply to the distribution of the material (of any kind, including +copyrighted graphics or logos) that is published with it. + +_* /{Write a first draft, revise, edit, improve, redo if necessary}/ + + - Brainstorm!. You need to organize your ideas first in a logical sequence + of events. + + - Once you have somehow organized those ideas in your mind write a first + draft. + + - Revise grammar, syntax and spelling. Keep in mind that the proper names + of the releases, such as ${testing} or sid, should not be capitalized + when referred to as code names. In order to check the spelling you can + run the "spell" target. i.e. #{make spell}# + + - Improve your statements and redo any part if necessary. + +_* /{Chapters}/ + +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. + +_* /{Markup}/ + +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 + +Here are some markup examples that may prove useful: + + - For emphasis/bold text: + +code{ + +*{foo}* or !{foo}! + +}code + +produces: *{foo}* or !{foo}!. Use it to emphasize certain key words. + + - For italics: + +code{ + +/{foo}/ + +}code + +produces: /{foo}/. Use them e.g. for the names of Debian packages. + + - For monospace: + +code{ + +#{foo}# + +}code + +produces: #{foo}#. Use it e.g. for the names of commands. And also to +highlight some key words or things like paths. + + - For code blocks: + +code{ + + code{ + + $ foo + # bar + + }code + +}code + +produces: + +code{ + + $ foo + # bar + +}code + +Use #{code{}# to open and #{}code}# to close the tags. It is important to +remember to leave a space at the beginning of each line of code. + +2~guidelines-translators Guidelines for translators + +This section deals with some general considerations to be taken into account +when translating the contents of live-manual. + +As a general recommendation, translators should have read and understood the +translation rules that apply to their specific languages. Usually, +translation groups and mailing lists provide information on how to produce +translated work that complies with Debian quality standards. + +*{Note:}* Translators should also read {Contributing to this document}#how-to-contribute. In particular the section {Translation}#translation + +3~ Translation hints + +_* /{Comments}/ + +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. + +_* /{TN, Translator's Note}/ + +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". + +_* /{Impersonal sentences}/ + +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. + +_* /{False friends}/ + +The trap of "false friends" explained before especially applies to +translators. Double check the meaning of suspicious false friends if in +doubt. + +_* /{Markup}/ + +Translators working initially with *{pot}* files and later on with *{po}* +files will find many markup features in the strings. They can translate the +text anyway, as long as it is translatable, but it is extremely important +that they use exactly the same markup as the original English version. + +_* /{Code blocks}/ + +Even though the code blocks are usually untranslatable, including them in +the translation is the only way to score a 100% complete translation. And +even though it means more work at first because it might require the +intervention of the translators if the code changes, it is the best way, in +the long run, to identify what has already been translated and what has not +when checking the integrity of the .po files. + +_* /{Newlines}/ + +The translated texts need to have the exact same newlines as the original +texts. Be careful to press the "Enter" key or type *{\n}* if they appear in +the original files. These newlines often appear, for instance, in the code +blocks. + +Make no mistake, this does not mean that the translated text needs to have +the same length as the English version. That is nearly impossible. + +_* /{Untranslatable strings}/ + +Translators should never translate: + + - The code names of releases (which should be written in lowercase) + + - The names of programs + + - The commands given as examples + + - Metadata (often between colons *{:metadata:}*) + + - Links + + - Paths |