Об авторе

Как оформлять документацию

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

Заголовки и просто текст

Тег <h2> используеться для указания основных разделов. Что именно считать основными разделами вы можете решить сами или посмотреть исходный код документации в оригинале.

За подразделы отвечает тег <h3> и ситуация по его использованию такая же как и в случае с заголовком <h2>.

Define - это стандарный вариант оформления начала фактически каждой страницы с документацией, где в начале идёт определение того или иного термина. Соответсвенно применяйте тег <p> для параграфа и тег <strong> для того чтобы выделить слово жирным.

Исходный код

С помощью тега <code> нужно оформлять код, названия сниппетов, классов, моделей и. т. д, которые встречаються непосредственно в предложении.

<p>Lorem ipsum dolor <code>nameSnippet</code> sit amet, consectetur adipisicing elit.</p>

За форматирование блоков кода отвечает тег <pre>. Было решено не использовать окрашивание кода различными javascript-скриптами и php-функциями, так как это не всегда это делаеться корректно и иной раз вызывает путаницу, поэтому никаких css-классов для блоков кода указывать не нужно.

Любой код не должен обрабатываться парсером браузера, поэтому используются html-entities, например:

  • &lt; - открывающая угловая скобка. С данного символа должен начинаеться любой html-тег.
  • &#91; окрывающая квадратная скобка. Данный символ часто применяеться на страницах MODx Revolution, где нужно сделать вызов сниппетов, чанков, TV и т. д.

Самые популярные сущности перечисленны в статье с документацией по HMTL - ссылка указана в конце статьи.

Достаточно заменить только открывающие элементы для того чтобы ваш код не смог обработаться парсером браузера.

Например, следующий фрагмет кода:

&#91;&#91;!getResources? &parents=`&#91;&#91;*id]]` &tpl=`myRowTpl`]]

&lt;form action="form.php" method="get">
    &lt;label>First name: &lt;input type="text" name="first_name">&lt;/label>
    &lt;label>Last name: &lt;input type="text" name="last_name">&lt;/label>
    &lt;input type="submit" value="Submit">
&lt;/form>

Даст в итоге следующую картину:

[[!getResources? &parents=`[[*id]]` &tpl=`myRowTpl`]]

<form action="form.php" method="get">
    <label>First name: <input type="text" name="first_name"></label>
    <label>Last name: <input type="text" name="last_name"></label>
    <input type="submit" value="Submit">
</form>

Для форматирования текста рекомендуеться использовать текстовый редактор Sublime Text 2. Отличие данного редактора от остальных ему подобных - это в том что он поддерживает снипеты, возможно использование Emmet и Zen Coding, нормально работает поиск и замена, тоесть можно делать замену символов для выделенного фрагмента кода, а не только во всём документе целиком (нужная вещь, но зато этого нет практически у всех редакторов кода), поддерживает мультикурсор.

Смотрите видеоуроки по Sublime Text на моём канале YouTube - ссылка на которые указана в конце статьи.

Блоки

Блоки выделенного текста - очень нужная вещь и позволяет заостирть внимание пользователя на тех или иных моментах. Не всегда данные фрагменты текста выделяються на страницах документации в оригинале, но как правило в начале таких блоков имеються одноименные обозначения такие как note, important, info, tip.

Блок текста, который используеться для различных заметок.

<p class="note"><strong>Примечание:</strong> ipsum dolor sit amet, consectetur....</p>

Примечание: Lorem ipsum dolor sit amet, consectetur adipisicing elit. Adipisci, ullam, facere, ex, saepe rerum dignissimos officia ipsam optio maxime ratione in voluptatibus laborum sed quod quas earum quisquam modi eligendi.

Блок текста с важной информацией - часто используеться на страницах с документацией по CodeIgniter.

<p class="important"><strong>Важно:</strong> Lorem ipsum dolor sit amet, consectetur ...</p>

Важно: Lorem ipsum dolor sit amet, consectetur adipisicing elit. Blanditiis, quisquam quis aliquid quos dolores dignissimos laudantium molestias soluta. Tempore, nesciunt unde corporis ipsa cupiditate corrupti asperiores in veritatis placeat obcaecati!

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

<p class="info"><strong>Примечание:</strong> Lorem ipsum dolor sit amet, consectetur...</p>

Информация: Lorem ipsum dolor sit amet, consectetur adipisicing elit. Enim, sapiente, esse, at recusandae ex nihil ut minus repellat aperiam accusantium deserunt consequatur corporis praesentium explicabo quam consequuntur excepturi tempora voluptatem.

Блок с советами.

<p class="tip"><strong>Примечание:</strong> Lorem ipsum dolor sit amet, consectetur...</p>

Совет: Lorem ipsum dolor sit amet, consectetur adipisicing elit. Eius, aliquam ex adipisci facilis aspernatur repellendus molestiae rem sint nobis doloremque eaque reiciendis qui cumque maxime voluptas. Asperiores vero hic error!

Любой из выше перечисленных блоков, может быть как единственным параграфом, тоесть тегом <p>, так и элементом <div>, который может содержать уже несколько элементов, такие как.

  • несколько параграфов
  • нумерованный список (списки)
  • не форматированный список (списки)
<div class="info">
    <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit...</p>
    <p>Expedita, quidem rerum quas ullam tempore dignissimos et facilis voluptatem...</p>
    <ul>
        <li>Lorem ipsum dolor sit amet.</li>
        <li>Voluptatibus a tenetur impedit sed.</li>
        <li>Fuga similique doloribus rem sunt.</li>
        <li>Expedita, dolores doloremque tempore voluptates.</li>
        <li>Illo accusamus consequatur quam totam.</li>
    </ul>
</div>

Таблица

Часто применяеться на страницах с документацией по языкам разметки и программирования, CMS MODx Revolution, где перечисляються разнообразные параметры.

<table>
    <tr>
        <th width="20%">Название</th>
        <th width="60%">Описание</th>
        <th width="20%">По умолчанию</th>
    </tr>
    <tr>
        <td><code>tpl</code></td>
        <td>Lorem ipsum dolor sit amet, consectetur adipisicing elit...</td>
        <td><code>1</code></td>
    </tr>
</table>

Но здесь стоит обратить внимание, что иной раз в первой и третьей колонке использование тега <code> может не понадобиться или же вообще третья колонка будет не нужна, тогда ширину первой колонки оставляет так как есть, а вторую устанавливаете в width="80%".

Название Описание По умолчанию
tpl Lorem ipsum dolor sit amet, consectetur adipisicing elit. Iusto, alias, eligendi, consequuntur, cupiditate error consectetur itaque voluptate quisquam expedita sed suscipit quia eveniet nam dolorem consequatur rerum vitae voluptatibus labore. 1

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

<table class="browser_support">
    <tr>
        <td>Internet Explorer</td>
        <td>Mozilla Firefox</td>
        <td>Google Chrome</td>
        <td>Opera</td>
        <td>Safary</td>
    </tr>
</table>
Internet Explorer 7+ Mozilla Firefox 3+ Google Chrome Opera Safary

Курсив

Курсив обознаеться тегом <i>, который определяет названия файлов, папок и команд программ и ихние пути. Разделителями путей выступают соответственно символ » - для команд, и символ / файлов и папок.

<p><i>Сайт » Обновить кэш</i></p>
<p><i>controllers/admin/login.php</i></p>

Сайт » Обновить кэш

controllers/admin/login.php

Список терминов

Иногда всё таки будет встречаться словарь терминов или глюсарий, поэтому в таких случаях нужно применять именно такое форматирование и стиль оформления.

<dl>
    <dt>HTML</dt>
    <dd>язык разметки гипертекста, который используеться для формирования...</dd>
    <dt>CSS</dt>
    <dd>язык визуальной разметки, который используеться для того...</dd>
    <dt>JavaScript</dt>
    <dd>язык программирования, который обрабатываються в браузере...</dd>
    <dt>PHP</dt>
    <dd>самый популярный серверный язык программирования...</dd>
</dl>
HTML
язык разметки гипертекста, который используеться для формирования структуры веб-страницы.
CSS
язык визуальной разметки, который используеться для того чтобы указать внешнее оформление веб-страниц.
JavaScript
язык программирования, который обрабатываються в браузере и используються для придания веб-странице различных эффектов и интерактивности
PHP
самый популярный серверный язык программирования для веб.

Не нумерованный список

На страницах с документацией встречаеться достаточно часто.

<ul>
    <li>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Vel, ad.</li>
    <li>Porro, tempore, dolores omnis voluptatibus tenetur officia esse quia maxime!</li>
    <li>Modi, adipisci velit voluptatem alias magni voluptatum rem reprehenderit nihil.</li>
    <li>Numquam, harum, dignissimos voluptate hic eligendi assumenda neque a possimus!</li>
    <li>Nam, odio et suscipit quos aliquid illo quaerat excepturi quia.</li>
</ul>
  • Lorem ipsum dolor sit amet, consectetur adipisicing elit. Vel, ad.
  • Porro, tempore, dolores omnis voluptatibus tenetur officia esse quia maxime!
  • Modi, adipisci velit voluptatem alias magni voluptatum rem reprehenderit nihil.
  • Numquam, harum, dignissimos voluptate hic eligendi assumenda neque a possimus!
  • Nam, odio et suscipit quos aliquid illo quaerat excepturi quia.

Нумерованный список

Как правило используется очень редко.

<ol>
    <li>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Sed, odio.</li>
    <li>Quasi, quam impedit cumque nihil unde alias error sapiente doloribus!</li>
    <li>Quibusdam, tempora, possimus cum ad error culpa ex nulla nam.</li>
    <li>Architecto, distinctio, cupiditate iure in blanditiis sequi tempora vitae ipsum.</li>
    <li>Quo aut repellat dolores eligendi eaque tenetur delectus voluptates iusto.</li>
</ol>
  1. Lorem ipsum dolor sit amet, consectetur adipisicing elit. Sed, odio.
  2. Quasi, quam impedit cumque nihil unde alias error sapiente doloribus!
  3. Quibusdam, tempora, possimus cum ad error culpa ex nulla nam.
  4. Architecto, distinctio, cupiditate iure in blanditiis sequi tempora vitae ipsum.
  5. Quo aut repellat dolores eligendi eaque tenetur delectus voluptates iusto.

Дополнительные ресурсы:

Наверх ↑

закрыть х
Новые уроки на постоянной основе!

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

  • Fireworks, Photoshop, Illustrator
  • HTML, CSS, JavaScript
  • PHP, MySQL
  • CMS, PHP фреймворки, JS библиотеки
  • Инфобизнес, Email-маркетинг
Бесплатно!

Только для email-подписчиков!