Category Archives: technical writing

Техническая коммуникация и документирование ПО

Сегодня второй день Зимней Школы по программной инженерии для выпускников ВУЗов’11, на которой я представила свой доклад о технической коммуникации и документировании ПО. Презентацию можно посмотреть здесь:
Техническая коммуникация и документирование ПО.pps (PowerPoint 2003 file)

Advertisements

Leave a comment

Filed under CMS, Confluence, Документация, документирование ПО, единый источник документации, управление проектами, technical communication, technical writing, Wiki

Пирамиды рассуждений

В университете нас учат тому, что любой доклад, отчет, курсовая работа должны состоять из следующих частей: Введение, Основная часть, Заключение. Однако том, как правильно излагать идеи и выстраивать ход рассуждений в каждой из них почти ничего не рассказывается, но должны же существовать какие-то подходы?
Конечно, они есть. Для того чтобы выстраивать последовательность рассуждений можно, например, использовать принцип пирамиды Минто (Minto Pyramid Principle@).
***

Принцип пирамиды

Принцип пирамиды – это подход к структурированию идей для представления их в максимально пригодной для восприятия письменной форме:
• Для группы идей одного уровня должно быть обобщающее утверждение. Обобщающее утверждение может быть в свою очередь одной из идей группы более высокого уровня абстракции и т.п.
• Идеи внутри группы должны быть логически взаимосвязаны.
• Идеи каждой группы должны идти в логической последовательности (хронологической, структурной, сравнительной).

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

Логика рассуждения

Рассуждение сводится к последовательному изложению групп идей в уже известной последовательности: Введение, Основная часть, Заключение. Идея, как определяет ее Минто, – это утверждение, которое дает читателю неизвестную информацию и вызывает у него подсознательный вопрос.

Введение. Введение должно содержать следующие элементы:
• Ситуацию
• Развитие ситуации
• Вопрос
• Ответ

Основная часть. Основная часть должна содержать рассуждение, построенное по принципу индукции (снизу вверх) или дедукции (сверху вниз). Если в основной части анализируется какая-то проблема, то для систематизации рассуждений и комплексного анализа проблемы можно использовать одну из моделей, описанных в книге Минто. Проблемы анализируется по схеме:
• Начальная сцена
• Событие, нарушающее равновесие
• Нежелательный Результат
• Желаемый результат
Заключение. Если документ небольшой, заключение можно не писать. Минто не рекомендует писать плохое заключение, лучше его не писать совсем. В заключении нужно перечислить ключевые идеи, на которых стоит заострить внимание читателя. В заключении можно сформулировать перспективы, призвать читателя к действию.

Как писать?

Можно выделить следующие советы:
• Повествование должно увлекать читателя и оставаться недосказанным, чтобы у читателя все время вызывался вопрос, но именно тот, на который автор хочет дать ответ в этом письме. Последовательно, вопрос за вопросом, писатель увлекает читателя и раскрывает свою мысль.
• Не сосредоточивайтесь на хорошем стиле изложения, сосредоточьтесь на идее. Нужно стараться как можно более точно сформулировать идею, мысль, которую нужно донести до читателя, а не на том, чтобы как можно более изящно подобрать слова и написать красивое предложение. Красивое, но пустое предложение будет для читателя бесполезной тратой времени, и не принесет ничего, кроме досады и разочарования.
• Используйте значащие заголовки. Кроме того, что они сообщают главную мысль каждого раздела и подраздела, содержательные заголовки позволяют лучше структурировать текст и составить удобное оглавление.

Подготовка слайдов

Исчерпывающим сборником советов и рекомендаций по подготовке слайдов Минто называет книгу Д. Желязны «Говори на языке диаграмм».
Из всех рекомендаций интересно правило выбора оптимального размера шрифта, цитируемое из книги Желязны, – «правило 3,8».
Правило 3,8: буква размером 1 см будет хорошо различима максимум на расстоянии 3,8 м (при условии, что размер букв определяется в см, а расстояние от экрана до зрителя в м).

Что почитать?

Принцип пирамиды изложен в книге, написанной самой Барбарой Минто. Вот полное название книги: Барбара Минто. Принцип пирамиды Минто. Золотые правила мышления, делового письма и устных выступлений.
Мне понравилась книга, она содержит большое количество примеров и написана понятным языком. Приведу ссылки на другие книги, упомянутые в «принципе пирамиды»:
• Генри Стрейндж. Milestones in Management (Минто пишет, что эта книга совершила переворот в управленческом мышлении).
• Джин Желязны. Говори на языке диаграмм (Минто отсылает к этой книге, которая описывает все тонкости разработки хороших презентаций).
• Images and Models, Similes and Metaphors // Metaphor and Thought / Andrew Ortony, editor. – Cambridge University Press, 1979 (об образном мышлении).

Приятного чтения!

Leave a comment

Filed under copy writing, Документация, technical communication, technical writing

I’m on SECR 2010!

This year I’m attending and speaking at the Software Engineering Conference taking place in Moscow, Russia.

The event is awesome. The key persons of the industry traditionally visit the event. Grady Booch, Ivar Jacobson, Lars Bak, Yuri Gurevich, Steve Masters are among the key speakers of the last years.

This time Bjarne Stroustrup comes to visit us at SECR (his program is here).

I’m looking forward to meet the icon!

My paper on ‘Supporting SaaS in Documentation Systems’ is submitted to the conference program. Yeah!

Now it’s time to prepare a presentation.

Leave a comment

Filed under CMS, Документация, документирование ПО, единый источник документации, IT conference, software documentation, tech writing, technical communication, technical writing, Wiki

A Useful Blog on Copywriting

About a year ago my friend showed me a very interesting blog – the Michael Fortin’s blog on copywriting, marketing and life.

It provides really useful and interesting information not only for copywriters. For instance, we can apply his explanations on differences between features, benefits and advantages in technical writing too:
The Oft-Confused Features And Benefits

Some of the statement techniques he tells about can help making technical information more clear and easy to understand.

Leave a comment

Filed under copy writing, Документация, software documentation, tech writing, technical writing

Tekom – Great Community for Technical Communicators

Today I have discovered a large international community for technical communicators – Tekom. It seems to be interesting. It performs conferences and exibitions, accredits educational course providers and does much more work on promoting our proffession – technical writer.
Tekom is a German organization. It has a bunch of useful articles on the official web site (English version is available): Tekom.de

Truly, it would be awesome to take part in the annual Tekom’s conference on technical communication. Anyone can send an interesting article or presentation to introduce at the conference.

Unfortunately, the paper submission deadline has already passed in this year (13 March). However, we can just attend the event in this year:)
This year Tekom’s conference will be hold from 3 to 5 November 2010 in Rhein-Main-Hallen, Wiesbaden.
For more information about the conference, see tcworld 2010 conference.

As I found Tekom I think about possible opportunities of improving my tech writing and communication skills. I search Tekom’s web site for learning courses and professional certifications, but found nothing.

Can anyone advice any certification programs? Which are the best and well-known? Where to go to advance professional skills in technical writing?

Leave a comment

Filed under документирование ПО, IT conference, software documentation, tech writing, technical communication, technical writing

Documentation in Agile Projects

I have an idea of preparing a report for SEC(R) 2010 about how to use Wikis for software and software project documentation getting the maximal profits from this technology. Wikis are the most suitable instrument for agile projects, where developers should rogirously economy resources and spend so little time for documentation as possible.
I would like to demonstrate all principles of effective agile documentation in the Confluence wiki system.

So, the questions are:
Is such a subject really interesting and possible to demonstrate to the public?
What aspects would you like to see and find out from this report?

SEC(R) stands for Software Engineering Conference (Russia), it is an annual conference with English and Russian speakers describing and discussing various issues of software engineering and development.

SEC(R) 2010 (Russian version of the web site, English version is under construction)
SEC(R) 2009 (English version of the web site created for the previous conference)

1 Comment

Filed under документирование ПО, project management, software documentation, tech writing, technical writing

Книги по документированию ПО на русском

На русском языке о документировании ПО написано мало. До сих пор мне попадалось очень мало книг, посвященных данной теме, и я решила составить их список с кратким резюме по каждой из них:

  1. Ю.В. Кагарлицкий. Разработка документации пользователя программного продукта. Полезна начинающему техническому писателю, которому впервые поручили написать пользовательскую справку, или человеку, начинающему работать с документацией. Содержит рекомендации по стилю изложения, советы по написанию максимально полезного и понятного хелпа.
  2. В. Глаголев. Разработка технической документации. Перечисляет системы стандартов, которые используют при документировании ПО, как старые советские (ЕСПД), так и относительно новые (ИСО). Книга в основном пересказывает стандарты и может быть полезна техническому писателю, работа которого жестко регламентирована требованиями ГОСТов, или писателю, желающему расширить свои знания о процессе разработки документации. Книга сложновата для восприятия.
  3. Липаев В.В. Документирование сложных программных средств. Монография, кратко описывающая процесс документирования, стандарты в области управления качеством, которые можно применить к документации. В книге рассматриваются вопросы организации процесса, необходимые условия работы, виды шаблонов документов, ответственности всех участников разработки ПО в документировании продукта. Книга написана довольно сложным для восприятия языком.

1 Comment

Filed under Документация, документирование ПО, technical communication, technical writing