Writing an Application Manual/ru: Difference between revisions
(Created page with "== Начальный этап написания учебника ==") |
(Created page with "На начальном этапе создания вашего учебника лучше держать его отдельно от остальных данных UserBa...") |
||
Line 58: | Line 58: | ||
== Начальный этап написания учебника == | == Начальный этап написания учебника == | ||
На начальном этапе создания вашего учебника лучше держать его отдельно от остальных данных UserBase. Можно редактировать черновики основной и подчиненных страниц на странице обсуждения вашей страницы пользователя. С этой целью нами также предусмотрен особое наименование <tt>Draft:</tt>. | |||
To create the content page of your manual, simply write <tt><nowiki>http://userbase.kde.org/Draft:</nowiki>'''''Appname/Manual'''''</tt> in the address line of your browser, or place the <nowiki>[[Draft:Appname/Manual]]</nowiki> link in a page and then click it. Either way you will be taken to a page telling you that the page does not exist, but that you can create it clicking a link. | To create the content page of your manual, simply write <tt><nowiki>http://userbase.kde.org/Draft:</nowiki>'''''Appname/Manual'''''</tt> in the address line of your browser, or place the <nowiki>[[Draft:Appname/Manual]]</nowiki> link in a page and then click it. Either way you will be taken to a page telling you that the page does not exist, but that you can create it clicking a link. |
Revision as of 12:52, 21 March 2013
Заметки
Учебники будут включены как подчиненные страницы к основной странице программы. Для краткости я буду называть, что главную страницу, какAPPNAME . Тогда структура страниц должен быть примерно такой:
- Appname
- Appname/Hints and Tips
- Appname/Manual # Your Contents page
- Appname/Manual/An Introduction to Appname
- Appname/Manual/Configuration Choices
- Appname/Manual/The First Time you use Appname
- Appname/Manual/section 1
- Appname/Manual/section xxx
- Appname/Manual/Hints and Tips
- Appname/Manual/Troubleshooting
- Appname/Manual/Bug reports
- Appname/Manual/Get involved #link to techbase etc
Если некоторые из разделов учебника становятся слишком большими, вы можете разместить подразделения на отдельных страницах. Структура может быть такой:
- Appname/Manual # Your Contents page
- Appname/Manual/An Introduction to Appname
- Appname/Manual/Configuration Choices
- Appname/Manual/The First Time you use Appname
- Appname/Manual/section 1
- Appname/Manual/section 1/subsection 1
- Appname/Manual/section 1/subsection 2
and so on.
Чтобы в автоматически созданном в учебнике в формате Docbook был тот же смысл, что и на UserBase, а ссылки в Docbook работали, следует придерживаться следующих установок:
- В содержании учебника в формате Docbook все разделы и подразделы будет показано независимо от того, есть ли у них своя страница. С другой стороны, подразделения высокого уровня вложенности не будет показано, даже если в этих подразделений является собственная страница.
- На каждой странице раздела в верхней части должен быть заголовок раздела (== ... ==), подраздела (=== ... ===) или подподраздела(==== ... ====), иначе структура учебника в формате Docbook будет отличаться от задуманного.
- Заголовок раздела или подраздела должно точно совпадать с названием страницы, иначе ссылки в Docbook будут работать не так, как это должно быть.
- Названия подразделений должно быть записано так:
===""'Название""'===
, даже если этот раздел является разделом наивысшего уровня на странице. Если не придерживаться этого правила, структуру Docbook будет искажено. Так же, если в вашем учебнике есть очень длинные подразделения, которые разделены на отдельные страницы, каждая из таких страниц должна иметь собственный заголовок в таком формате:====""'Название""'====
.
- Подразделения, которые не должно быть показано на странице содержания, и которые не имеют собственной страницы, в Docbook имеют уровень 4 или ниже, то есть заголовок уровня==== или ниже.
- Ссылки на страницах учебника должны точно совпадать с названиями страниц (т.е. не должно быть переименований)
- Если вы делаете ссылку на подраздел страницы, вам следует добавить отметку в соответствующем месте страницы. Если вы этого не сделаете, ссылки в переводах не будут работать.
Вам понадобится некий черновик для экспериментов с заголовками разделов и страниц учебника. Вы можете воспользоваться или собственной страницей обсуждения, или страницами из участка, над которой вы работаете. После завершения работы следует удалить все лишние страницы.
Начальный этап написания учебника
На начальном этапе создания вашего учебника лучше держать его отдельно от остальных данных UserBase. Можно редактировать черновики основной и подчиненных страниц на странице обсуждения вашей страницы пользователя. С этой целью нами также предусмотрен особое наименование Draft:.
To create the content page of your manual, simply write http://userbase.kde.org/Draft:Appname/Manual in the address line of your browser, or place the [[Draft:Appname/Manual]] link in a page and then click it. Either way you will be taken to a page telling you that the page does not exist, but that you can create it clicking a link.
Contents
- Once you have made the decisions (that can be a lengthy procedure), create appropriate links on the Contents page. It is, of course, possible to insert a section later if you find you've missed something.
Building your Manual
- Use the red links to create the page, and write up a section at a time.
- Note on the Discussion page anything you will need to refer to later, such as links that can't yet be created.
- Take care with heading levels - we start at second level (Mediawiki uses top level for page-name), using ==
- Make sure you refer frequently to this page, to Tasks and Tools and to Typographical Guidelines
- Check if all table cells have space after the pipe character. This rule conforms with traditional wiki formatting.
- Make application name formatting consistent (avoid using Amaroks, do use Amarok's).
- Ensure that all images are in PNG format (you can use JPEG as well, but in this case they should be converted to PNG by the script). Save work by converting them before you start .
- Remove all non-printable characters from image names.
Searching your manual
At some point, you may need to find something that you wrote earlier, but can't remember where. Using the wiki search box may not be ideal unless the string you search for is very specific. You can get much better control over searches using the DPL extension. For example, to find the pages in your manual containing a certain string, you can add the following to any page:
<DPL> titlematch = %Appname/Manual% namespace = Draft include = * includematch = /string to search for/ resultsheader = Manual Pages: format = ,\n* [[%PAGE%|%TITLE%]]\n,, </DPL>
You can find more examples on using DPL on User:Claus_chr/DPL.
Preparing the Manual for Translation
- The steps for markup editing can be found on Preparing a Page for Translation. Please adhere to that guide, since old markup styles may not still be relevant.