====== Принципы ведения документации SliTaz ===== Этот документ содержит рекомендации по написанию статей вики и задачи, которые должны быть выполнены, чтобы сделать документацию SliTaz актуальной. ===== Пересмотр документации ===== - Централизация всей документации на [[http://doc.slitaz.org]] - Полная миграция «Настольной книги» и «Поваренной книги» (и «SliTaz с самого начала», если это возможно) - Перевод «Настольной книги» и «Поваренной книги» - Связывание ссылками или перевод статей вики на [[http://labs.slitaz.org|веб-сайте лабораторий]] - Пересмотр и обновление «Настольной книги» и «Поваренной книги» к версии 3.0 - Добавление новых руководств. Лист пожеланий по руководствам находится на [[http://doc.slitaz.org/en:guides:start|странице руководств]] в качестве отправной ссылки - Пересмотр и обновление существующих руководств ===== Общие указания ===== * **Добавляйте**: Не стесняйтесь добавлять любые страницы в вики * __Пространства имен или структура документации__: Структура документации была определена для английского языка. Придерживайтесь ее в качестве стандарта при создании страниц. Несколько примеров: * //en:handbook:start//: Начальная страница «Настольной книги» * //en:handbook:desktop//: Desktop — это ссылка на страницу с начальной страницы «Настольной книги». Все страницы «Настольной книги» должны находиться в пространстве имен "en:handbook:" * //en:guides:faq//: Все страницы руководств должны находиться в пространстве имен "en:guides". Чтобы создать страницу ЧаВо (Часто задаваемых Вопросов), просто создайте ссылку [[faq | ЧаВо]]. Это автоматически создаст страницу ЧаВо в нужном пространстве имен en:guides:faq * //Index//: Ссылки могут быть использованы для просмотра структуры документации * __Добавляйте изображения__: Используйте панель инструментов для добавления изображений с соответствующее пространство имен * **Удаляйте**: Просто удалите всё содержимое страницы для того, чтобы удалить страницу * **Обзор**: Каждая страница должна содержать раздел обзора. К примеру, [[#форматирование|внизу этой страницы]]. Раздел обзора — это просто таблица вики. Вы вольны изменять эту таблицу и/или добавлять в нее дополнительные строки. Вы можете перевести ее на свой родной язык. Также вы можете скопировать эту таблицу с данной страницы и вставить ее на любую другую страницу вики, соответственно отредактировав ===== Шаблон страницы ===== Существует несколько определенных стилей страниц, в которые мы можем поместить содержимое. === ЧаВо === Следующее относится к одной странице, [[en:guides:faq|Frequently Asked Questions]]. - **Сообщения об ошибках** — озаглавьте каждый вопрос-ответ наиболее подходящим описанием, обычно отображаемым сообщением об ошибке. - **Симптомы** — короткое описание, что пользователь может получить при применении этого ЧаВо. Их может быть более одного. Используйте правильное форматирование при описании экранных сообщений, сочетаний клавиш и т.п. Надеемся, что поиск Google приведет пользователей именно сюда. - **Объяснение** — не слишком техническое описание сообщения об ошибке. Пользователи смогут понять проблему и то, как ее можно решить в лучшем виде. - **Решения** — как решить проблему технически. Включая краткие описания необходимых шагов, а не просто список команд; это важно для понимания того, что пользователь должен сделать. Если различные проблемы имеют слегка разные решения — применяйте для их организации списки. === Обзоры === Они находятся в пространстве имен <язык>:guides:<тема>. Они описывают процесс, как заставить что-либо работать. - **Введение** — Summarize the article - **Графически** * Инструкции — How to use the graphical tool (if it exists) * Снимки экрана — Картинка лучше, чем тысяча слов - **Вручную** * Установка — Define the packages required and how to install them * Настройка — Explain how to configure files for the proper functioning of packages * Summarize — If possible, summarize all commands in one single script for troubleshooting - **Примеры и подсказки** — Add some examples and advanced tips - **FAQ/Troubleshooting** — Some DIY instructions or a sub-section on problems/symptoms/solutions/notes or a link to forum posts. Link to FAQ if answered there - **References** — Other good reference material on the Internet. If there aren't any, consider a message asking for some! === «Настольная книга» === These reside under the :handbook: namespace. They brief the reader on what SliTaz can offer on a particular topic. They are an overview and description and not a guide, though they may contain (very) few steps on how to get up-and-running. - **Blurb** — describes the content of the page, in terms of scope. - **Topic** — what the user expects to achieve, e.g. 'Image Processing' or 'Desktop Themes' - **Body Text** — an overview of the topic, with links to relevent Guides or external web pages. - **Tips** (optional) — any problems the user may experience. Link to FAQ if answered, forum posts, good problem-solving web pages etc. ===== Форматирование ===== Используйте правильное форматирование везде, где это возможно. Это улучшит читабельность и исправит непонимание, где вводимые команды, а где их вывод, и т.п. * Изучайте синтаксис вики [[http://doc.slitaz.org/wiki:syntax?s[]=playground | здесь]]. Для опробования новых знаний синтаксиса просто используйте специальную страницу — [[http://doc.slitaz.org/en:guides:playground| песочница]] ---- ^ Раздел обзора страницы ^^ |Качество| хорошее | |Обзор| должно быть просмотрено | |Приоритет| средний | |Проблемы| добавить [[http://forum.slitaz.org|ссылку на форуме]]| |::: | ИЛИ добавить [[http://labs.slitaz.org/issues|ссылку в трекере неисправностей лабораторий]]| |Как улучшить| предлагайте кратко, например,| |::: | [[http://labs.slitaz.org/wiki/packages|Здесь находятся новые руководства по тестированию пакетов]] | |::: | Добавляйте новые строки, такие, как эта ;-) | \\ ----