Профессия "Технический писатель", или "Рыцари клавиатуры"

 ГОСТ — это государственный стандарт оформления различной технической документации, действующий на большей части СНГ. Он регламентирует формат текста (списки, рисунки, шрифты и т. д.), а также содержание самого документа. Например, указывает, какие документы и какие пункты в них должны содержаться, чтобы устройство было запатентовано или предоставлено на тендер по государственным закупкам.

Документы по ГОСТ оформляются только тогда, когда это требуется — соблюдать данный стандарт в пользовательской или внутренней документации не всегда целесообразно по той причине, что они будут содержать много лишних сведений, не являющихся необходимыми для пользователя. Вторая негативная черта — в стандарте есть предустановленные жёсткие формулировки, которые нельзя нарушать — в итоге текст состоит по большей части из многократно повторяющихся слов и предложений.

Единые государственные стандарты в области конструкторской, программной и технологической и руководящей документации

 Существует три основных единых стандарта: программной (ГОСТ 19), конструкторской (ГОСТ 2), технологической (ГОСТ 3) и руководящей (РД) документации. Также применяется ГОСТ 34 — на автоматизированные системы. Ознакомиться с ними подробнее можно в сети Интернет по соответствующим запросам, ибо на каждую область есть свой ГОСТ и на описание управления каждым оборудованием — своя РД. По сути, ГОСТ для техписа — это как таблицы Брадиса для математика — нужно знать как им пользоваться, но заучивать что-то наизусть смысла не имеет — всё необходимое чётко прописано в самом стандарте.

ISO и IEEE

 Эти международные стандарты применяются во всём мире, кроме, соответственно, стран, применяющих ГОСТ. Практически вся документация ко всей электронной технике и ПО, разрабатываемая повсюду в мире, исключая руководства для домашних пользователей, выполняется в соответствии с ними. Знание этих стандартов в настоящее время требуется лишь в том случае, если вы работаете в зарубежной компании или планируете переезд за рубеж.

IEEE 1063 — это стандарт, разработанный Институтом инженеров по электротехнике и электронике (IEEE) и содержащий все регламенты по документированию разработок в этих областях. К большому сожалению, разработок в этой отрасли в РФ очень мало (они есть, но их доля на рынке исчезающее мала), поэтому знание этих стандартов будут практически бесполезны для работы внутри РФ, но весьма ценны при написании документации для зарубежных компаний на основе, например, аутсорсинга.

ISO (ISO/IEC FDIS 18019:2004 и ISO/IEC 26514:2008) — собственно, это стандарт-руководство по написанию руководств. В отличие от IEEE, ISO может использоваться где угодно и поэтому порой встречается даже в РФ. Это связано с тем, что существуют компании, которые работают в том числе и для иностранных клиентов и, соответственно, вынуждены готовить русско- и англоязычные документы по международным стандартам.

Аналогично ГОСТу, нужно уметь читать эти стандарты и знать где их найти — хранить их в голове как таблицу умножения вовсе необязательно. Это справочная информация, которая всегда доступна и которую нужно уметь применять на практике.

Небольшую статью про эти стандарты можно прочитать здесь: http://habrahabr.ru/post/l16825/.

2. Документирование API

 API — интерфейс программирования приложений. В современном мире приложения и устройства общаются между собой на особых языках, которые и называются API того или иного устройства, веб-сервиса или приложения.

Технический писатель, описывающий API (их часто называют API technical writer), должен глубоко разбираться в продукте, который описывает, почти на уровне разработчика.

API technical writer пишет для других разработчиков, поэтому должен также владеть инструментами разработки.

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

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

Полезная статья о том, что такое API, для чего используется, зачем и как начать его документировать, какие инструменты использовать, как взаимодействовать с коллегами, какие существуют основные принципы: https://protext.su/pro/itak-vam-nuzhno-dokumentirovat-api/

Полезные ссылки и материалы