Writing an Application Manual/ru: Difference between revisions

    From KDE UserBase Wiki
    (Created page with "* Воспользуйтесь ссылками красного цвета для создания страниц, создавая разделы учебника один ...")
    (Created page with "* Записывайте на странице обсуждения все нужные впоследствии ссылки, в частности ссылки, данные...")
    Line 70: Line 70:
    * Воспользуйтесь ссылками красного цвета для создания страниц, создавая разделы учебника один за одним.
    * Воспользуйтесь ссылками красного цвета для создания страниц, создавая разделы учебника один за одним.


    * Note on the Discussion page anything you will need to refer to later, such as links that can't yet be created.
    * Записывайте на странице обсуждения все нужные впоследствии ссылки, в частности ссылки, данные для которых еще не создано.


    {{Remember|1=It's important to be consistent, particularly in Manuals, so here are some general rules:<!--}}-->
    {{Remember|1=It's important to be consistent, particularly in Manuals, so here are some general rules:<!--}}-->

    Revision as of 12:54, 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.

    Information

    Названия страниц не должны точно соответствовать структуре документа. В приведенном выше примере вы можете просто воспользоваться названием Программа/Учебник/"подраздел 2" вместо Программа/Учебник/"раздел 1"/"подраздел 2". То же касается низших уровней иерархии (конечно же, если в процессе названия не дублируются ).


    Remember

    Старайтесь использовать короткие названия и избегать слишком длинных путей в названии. Слишком длинные названия являются трудными для запоминания и введения, они выглядят неуклюже на страницах вики. Всегда помните: названия страниц и структура не влияют на завершенный вид учебника! Он определяется только заголовками в тексте.


    Чтобы в автоматически созданном в учебнике в формате Docbook был тот же смысл, что и на UserBase, а ссылки в Docbook работали, следует придерживаться следующих установок:

    • В содержании учебника в формате Docbook все разделы и подразделы будет показано независимо от того, есть ли у них своя страница. С другой стороны, подразделения высокого уровня вложенности не будет показано, даже если в этих подразделений является собственная страница.
    • На каждой странице раздела в верхней части должен быть заголовок раздела (== ... ==), подраздела (=== ... ===) или подподраздела(==== ... ====), иначе структура учебника в формате Docbook будет отличаться от задуманного.
    • Заголовок раздела или подраздела должно точно совпадать с названием страницы, иначе ссылки в Docbook будут работать не так, как это должно быть.
    • Названия подразделений должно быть записано так: ===""'Название""'===, даже если этот раздел является разделом наивысшего уровня на странице. Если не придерживаться этого правила, структуру Docbook будет искажено. Так же, если в вашем учебнике есть очень длинные подразделения, которые разделены на отдельные страницы, каждая из таких страниц должна иметь собственный заголовок в таком формате: ====""'Название""'====.
    • Подразделения, которые не должно быть показано на странице содержания, и которые не имеют собственной страницы, в Docbook имеют уровень 4 или ниже, то есть заголовок уровня==== или ниже.
    • Ссылки на страницах учебника должны точно совпадать с названиями страниц (т.е. не должно быть переименований)
    • Если вы делаете ссылку на подраздел страницы, вам следует добавить отметку в соответствующем месте страницы. Если вы этого не сделаете, ссылки в переводах не будут работать.

    Note

    В учебнике в формате DocBook каждое подразделение (===) будет иметь отдельную страницу, даже если это подразделение является частью более длинной страницы UserBase. Это означает, что раздел (==), который состоит из нескольких подразделений, но не содержит текста перед первым подразделением, будет иметь страницу Docbook, на которой не будет ничего, кроме ссылок на подразделы.


    Remember

    Если вам захочется изменить заголовок основного подразделения страницы (первый заголовок), важно также изменить соответствующим образом название страницы и все ссылки так, чтобы они совпадали с новым названием.


    Remember

    пожалуйста, не используйте знаки препинания в названиях страниц - знаки препинания, в частности знаки вопроса или точки, является достаточно серьезной проблемой для программного обеспечения вики, в частности системы перевода.


    Вам понадобится некий черновик для экспериментов с заголовками разделов и страниц учебника. Вы можете воспользоваться или собственной страницей обсуждения, или страницами из участка, над которой вы работаете. После завершения работы следует удалить все лишние страницы.

    Начальный этап написания учебника

    На начальном этапе создания вашего учебника лучше держать его отдельно от остальных данных UserBase. Можно редактировать черновики основной и подчиненных страниц на странице обсуждения вашей страницы пользователя. С этой целью нами также предусмотрен особое наименование Draft:.

    Чтобы создать страницу содержания вашего учебника, просто укажите в поле адреса вашей программы для просмотра интернет http://userbase.kde.org/Draft:""'Appname/Manual""' или вставьте ссылку [[Draft:Appname/Manual]] на страницу, сохраните его, а затем нажмите его. В обоих вариантах действий будет открыта страница с сообщением о том, что страницы не существует, но вы можете создать ее нажатием ссылки.

    Содержание

    • Когда все решение будет принято (процесс составления плана может быть довольно длительным), создайте соответствующие ссылки на страницы содержания. Конечно же, если вы пропустили нечто, позже можно будет добавить соответствующую ссылку.

    Сборка учебника

    • Воспользуйтесь ссылками красного цвета для создания страниц, создавая разделы учебника один за одним.
    • Записывайте на странице обсуждения все нужные впоследствии ссылки, в частности ссылки, данные для которых еще не создано.

    Remember

    It's important to be consistent, particularly in Manuals, so here are some general rules:
    • Take care with heading levels - we start at second level (Mediawiki uses top level for page-name), using ==
    • 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