DocFactor: конференція про технічної документації

Історично склалося так, що російські технічні письменники дещо обділені професійними заходами: конференцій про технічної документації в Росії досить мало (принаймні, значно менше, ніж по розробці або тестування), а в Сибіру їх взагалі практично немає.

Ми вирішили, що цю ситуацію слід змінювати, тому зустрічайте:




Читати далі →

7 правил написання технічної документації світового класу

Введення

Написання технічного документа — важка справа. Читання погано написаного технічного документа є більш важким і, ймовірно, більш болючою справою, ніж його написання. Потрібна велика робота, щоб створити ясне, точне, цікаве технічний опис. Тому, щоб зробити життя хоч трохи простіше для всіх сторін, я хотів би поділитися з вами сім'ю правилами, яким я слідую, створюючи технічну документацію.

Ці правила — не мій власний винахід. Скоріше, я просто сформулював їх з того досвіду, який з'явився завдяки спілкуванню з багатьма талановитими технічними та літературними редакторами за більш ніж десять років роботи. Все, що я зрозумів у цій справі, сформувалося тому, що інші показали мені шлях. У мене не знаходиться достатньо слів, щоб висловити їм повною мірою мою подяку.

Сподіваюся, після прочитання цієї статті у вашому арсеналі з'являться деякі нові інструменти, які допоможуть вам створювати технічні документи на новому рівні якості: більш ясні, більш привабливі, менш плутані і набагато більш цікаві для читання. Також я додав — без всяких будь-яких додаткових вимог до вам, як споживачеві, бонус в кінці статті: опис процесу, використовуваного мною для створення технічного опису.

Отже — ці 7 правил:
  1. Нудьга вбиває
  2. Перш ніж почати, точно з'ясуйте для себе, які дії ви очікуєте від читача, осилившего ваша праця
  3. Пишіть у відповідності з вірно сформованою структурою
  4. Уникайте неоднозначних займенників
  5. Ясність = ілюстрації + слова
  6. Коли маєте справу з поняттями, концепціями і т. п., використовуйте логічну ілюстрацію і приклад
  7. Не бійтеся переробок

Читати далі →