Writing an Application Manual/uk

Нотатки

Підручники буде включено як підлеглі сторінки до основної сторінки програми. Нехай, основна сторінка програми має назву Appname. Тоді структура сторінок має бути десь такою:

• Appname
  • Appname/Hints and Tips
• Appname/Manual # Сторінка змісту
  • 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 # посилання на сторінку techbase тощо

Якщо деякі з розділів підручника стають занадто великими, ви можете розташувати підрозділи на окремих сторінка. Структура може бути такою:

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

In order for the automatically generated Docbook to have the same contents page as the one you make on UserBase, and for links to work in the Docbook there are a couple or guidelines, that must be followed:

• The Docbook Table of Contents will list all sections and subsections regardless of whether they have a page of their own. On the other hand, subsubsections won't be listed in the Docbook TOC even though they have a page of their own.

• All pages should have a heading at the very top, either a section (== ... ==), a subsection (=== ... ===), or a subsubsection (==== ... ====), otherwise the Docbook structure will be messed up.

• The title of the section/subsection must exactly match the page name, otherwise Docbook links won't work.

• Subsection titles must be written like this: ===title===, even if it is the top level on a page. Otherwise the Docbook structure will be messed up. Similarly, if you have a very long subsection with subsubsections on pages of their own, these pages must have their titles written like this: ====title====.

• Subsubsections that should not appear in the contents page and should not appear on a page of its own in the Docbook must be level 4 or below, i.e ==== or more.

• Links to pages in the manual must exactly match the page name (i.e. no links via redirects!)

• If you link to a subsection of a page, you must have an anchor at the target location. Failing that will mess up Docbook links as well as translations.

Note

Every subsection (===) gets a page of its own in the Docbook, even if it is part of a longer page on UserBase. This means that a section (==) that contain a number of subsections, but no text before the first subsection gets a Docbook page that contains nothing but links to the subsections.

Remember

If at some point you decide to change the title of the main (sub)section of a page (the first headline), it is important that you also change the name of the page accordingly, and also that all links to that page are modified to match the new name.

Пам’ятайте!

Будь ласка, не використовуйте знаки пунктуації у назвах сторінок — знаки пунктуації, зокрема знаки запитання або крапки, є доволі серйозною проблемою для програмного забезпечення вікі, зокрема системи перекладу.

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

Початковий етап написання підручника

На початковому етапі створення вашого підручника краще тримати його окремо від решти даних UserBase. Можна редагувати чернетки основної та підлеглих сторінок на сторінці обговорення вашої сторінки користувача. З цією метою нами також передбачено особливий прострі назв Draft:.

Щоб створити сторінку змісту вашого підручника, просто вкажіть у полі адреси вашої програми для перегляду інтернету http://userbase.kde.org/Draft:Назва_програми/Назва_підручника або вставте посилання [[Draft:Appname/Manual]] на сторінку, збережіть його, а потім натисніть його. За обох варіантів дій буде відкрито сторінку з повідомленням про те, що сторінки не існує, але ви можете створити її натисканням посилання.

Зміст

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

Збирання підручника

• Скористайтеся посиланнями червоного кольору для створення сторінок, створюючи розділи підручника один за одним.

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

Пам’ятайте!

Під час написання підручника варто дотримуватися певних правил, які зроблять вашу роботу однорідною:

• Слідкуйте за заголовками рівнів — починати слід завжди з другого рівня (у Mediawiki перший рівень використовується для назви сторінки), тобто слід використовувати ==

• Зазирайте час від часу на сторінки завдань та інструментів та правил форматування.

• Додавайте пробіл після символу вертикальної риски у таблицях. Це правило узгоджується з традиційним форматуванням вікі.

• Використовуйте однорідну систему форматування для назв програм (використовуйте замість Amaroks формат Amarok's).

• Намагайтеся використовувати зображення лише у форматі PNG (можна використовувати JPEG, але під час створення Docbook скрипт все одно перетворить їх на зображення у форматі PNG). Ви можете зекономити час, якщо зробите все правильно від початку .

• Не використовуйте символи Unicode (не ASCII) у назвах зображень.

Пошук у вашому підручнику

У вас може виникнути потреба у пошуку чогось, що ви писали раніше, але не пам’ятаєте, де саме. Використання поля пошуку вікі може буде неідеальним, якщо ви не шукаєте щось дуже специфічне. Набагато кращі результати пошуку можна отримати за допомогою розширення DPL. Наприклад, щоб знайти сторінки підручника, які містять певний рядок, ви можете додати на будь-яку сторінку такий код і натиснути кнопку попереднього перегляду:

<DPL>
  titlematch = %Appname/Manual%
  namespace = Draft
  include = *
  includematch = /string to search for/
  resultsheader = Manual Pages:
  format = ,\n* [[%PAGE%|%TITLE%]]\n,,
</DPL>

Інші приклади використання DPL можна знайти на сторінці User:Claus_chr/DPL.

Приготування підручника до перекладу

• Кроки з редагування розмітки можна знайти на сторінці приготування сторінки до перекладу. Скористайтеся порадами з цієї сторінки, оскільки застарілі стилі розмітки можуть бути непридатними до використання.