Как понять, подходит ли вам профессия технического писателя¶
Дата публикации: 08.05.2024
Спойлер
Прикинуть, подходит ли вам профессия технического писателя, очень просто. Возьмите достаточно простой, но не слишком примитивный предмет (раскладной диван, ручной блендер, калькулятор в вашем смартфоне), и напишите инструкцию по его использованию. Затем оцените: получилось? Понравилось? Отложите на несколько дней, потом вернитесь к тексту и сделайте его лучше. Повторите пару раз, выбрав другие объекты для описания. Если вам все еще не надоело, то, возможно, эта профессия действительно для вас.
Что свойственно техническому писателю¶
Чтобы понять, подходит ли вам профессия технического писателя, оцените, насколько вам присущи следующие качества и умения или готовность их приобрести:
Грамотная письменная речь
Тут, думаю, долго объяснять не нужно. Писатель должен быть грамотным. Как мне кажется, человек, у которого была по русскому в школе тройка, и сам не пойдет в писатели.
Умение работать с текстом
Умение работать с техническим текстом включает в себя много навыков. Но основную суть можно выразить так: это умение изложить мысль максимально ясно и точно. Чтобы достигнуть этой цели, писателю приходится по многу раз переписывать свой текст, перекраивать его структуру, каждый раз глядя критическим взглядом и задавая себе вопрос «как сделать лучше?» Если вам такая работа кажется унылой, то вряд ли вам подойдет профессия технического писателя.
Умение объяснять сложные вещи простым языком
Я считаю профессию технического писателя сродни профессии учителя или репетитора. Нужно уметь объяснять доходчиво, уметь разложить сложный предмет на простые части и преподнести эти части в правильном порядке.
Умение подчинять творческие порывы требованиям и стандартам
Если вам нравится писать, это еще не значит, что вы можете стать техническим писателем. Возможно, вам нравится самовыражаться через тексты, а это совсем не то, что нужно в технической документации. Личность автора в технических текстах практически не видна, вся его творческая энергия уходит на созидание текстов, соответствующих заданным стандартам, шаблонам, правилам, коих может быть очень много, и все надо помнить и соблюдать. Про ГОСТ слышали? Эта аббревиатура довольно часто встречается в описаниях вакансий для технических писателей.
Интерес к предметной области
Что вам интересно было бы описывать? Компьютерные программы? Автомобили? Медицинские приборы? Определитесь с областью ваших интересов, хотя бы потенциальной.
Отсутствие интереса к предметной области чревато нежеланием углубляться в детали и разбираться в устройстве описываемых объектов или процессов, и, как следствие, некачественной документацией. Вам будет скучно, трудно и лень.
Совсем другое дело, когда вам любопытно разобраться, понять, узнать что-то новенькое. Делая предметную область понятной для себя, вы можете сделать ее понятной и для своих читателей.
Попробуйте писать¶
В конце концов, вы можете не гадать и не оценивать, а попробовать себя в деле. Профессия технического писателя это позволяет как никакая другая. Ведь если вы хотите стать, к примеру, стоматологом, у вас такой возможности нет. Никто в здравом уме не даст ковырять у себя в зубах просто потому, что вы сегодня решили выяснить, подходит ли вам профессия стоматолога. Чтобы стать автомехаником, юристом, бухгалтером, пилотом и много много еще кем, сначала придется освоить азы профессии, а потом уже практиковаться.
К счастью, для технических писателей все намного проще. Все, что нужно для начала, у вас уже есть: писать вы научились еще в начальной школе, за предметом для описания далеко ходить не надо, берите то, что под рукой. Как я уже сказала в спойлере выше: напишите инструкцию к чему-нибудь не слишком примитивному. Если процесс вас увлекает и не кажется унылым – уже хорошо. Если вы готовы показать результат кому-то, и этот результат оценят как годный – еще лучше. А если оценка будет не очень? Готовы вы переписать еще раз, а потом еще раз, чтобы стало лучше? Или как-то пропало желание стать техническим писателем? Если не пропало и готовы… ну, вы поняли.
Что потом¶
Сказанное выше не означает, что стать техническим писателем очень просто. Не очень просто. Когда вы поймете, что это «ваше», придется еще многому научиться. В частности, если вы планируете стать техническим писателем в IT, вам придется стать технически грамотным в этой сфере. Практически наверняка нужно будет освоить HTML, а с ним и CSS. Скорее всего, не избежать знакомства с системами контроля версий вроде Git или CVS. Будет отлично, если научитесь хотя бы чуть-чуть программировать, например, на языке Python. Добавьте к этому ПО, в котором вы будете непосредственно разрабатывать документацию.
По моим наблюдениям, за 15 лет уровень технической грамотности техписателей в IT очень вырос. Это коррелирует с ростом популярности Docs as Code – подхода, при котором документацию разрабатывают так же, как код, то есть с применением того же инструментария и тех же процессов. Так, например, в Docs as Code вместо визуальных текстовых процессоров вроде MS Word используют текстовые редакторы вроде Notepad++, Sublime Text или Atom, и структурируют текст с помощью легковесных языков разметки, таких как Markdown или reStructuredText. А затем с помощью генератора документации (MkDocs, Sphinx) из «сырых» файлов получают документацию в формате HTML, реже PDF.
Пример текста с разметкой reStructuredText:
Add conditional content with ifconfig
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*Conditional content* is published to the output only if it matches the
specified conditions. In our project, this condition is the language of
the document.
For Sphinx to process the conditional text, it needs the
`ifconfig <https://www.sphinx-doc.org/en/master/usage/extensions/ifconfig.html>`_
extension. Add ifconfig to the extensions list in conf.py:
.. code-block:: python
extensions = ['sphinx.ext.ifconfig']
Now we will add some information about translation of the text to
index.rst. This information is not needed in the original document, so
we will exclude this text from English.
А вот так этот фрагмент выглядит в уже опубликованном документе:
Впрочем, Docs as Code не вездесущ. Кто-то использует для разработки документации старый добрый MS Word, кто-то закупает специализированное ПО вроде MadCap Flare или Author-it, нередко документацию ведут в Confluence. Со временем во всем разберетесь и поймете, что вам ближе.
