Советы по грамотному написанию технической документации для пользователей.
Часть 3 (заключительная)

Заключение руководства нашего технического писателя Андрея Старовойтова, которое поможет сделать вашу пользовательскую документацию проще и понятнее.



На этот раз мы поподробнее рассмотрим:

• концептуальные топики (concept pages);
• справочные топики (reference pages);
• топики, в которых рассказывается, как решить какую-нибудь проблему (troubleshooting pages);
• где и как использовать скриншоты;
• а также дадим пару советов тем, кто пишет документацию на английском.

Предыдущие части: наш подход к документированию и локализации; советы по документированию часть 1 и часть 2.

Я потратил прилично времени на структуризацию и автоматизацию сборки фронта. Задача это интересная и стоит того, чтобы о ней рассказать.

Что умеет делать сборщик:

• Собирать front-end проект для development & production окружений.
• Собирать по несколько js/css бандлов на проект.
• Использовать стиль CommonJS модулей в браузере.
• Использовать ES6-синтаксис.
• Спрайты, картинки и многое другое.

Чтобы не иметь проблем с зависимостями и модулями при большом количестве браузерного javascript, обычно используют require.js. Также многие знают, что это всего лишь один из многих загрузчиков стандарта AMD, и у него есть альтернативы. Но мало кто знает, как они устроены внутри. На самом деле, написать подобный инструмент не сложно, и в этой статье мы шаг за шагом напишем свою версию загрузчика AMD. Заодно разберемся с Promise, который недавно появился в браузерах и поможет нам справиться с асинхронными операциями.

Основой require.js, является функция require(dependencies, callback). Первым аргументом передаем список модулей для загрузки, а вторым – функцию, которую вызовут по окончании загрузки, с модулями в аргументах. Используя Promise написать её совсем несложно:

function require(deps, factory) {
  return Promise.all(deps.map(function(dependency) {
    if(!modules[dependency]) {
      modules[dependency] = loadScript(dependency);
    }
    return modules[dependency];
  }).then(function(modules) {
    return factory.apply(null, modules);
  });
}

Конечно, это еще не всё, но основа есть. Поэтому продолжим.