Category Archives: Документация

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

Сегодня второй день Зимней Школы по программной инженерии для выпускников ВУЗов’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

Орфографический словарик: телекоммуникации

  • Демоверсия, деморежим
  • ТВ-каналы, ТВ-передачи, ТВ-программа
  • Радиоканалы
  • Караоке-запись, караоке-трансляция, караоке-клуб
  • PIN-код
  • Видеовыход
  • Видеосервер, мн. число им.п. – видеосерверы
  • Договор, мн. число им. п. – договоры
  • Фотосервис
  • Мультимедиасистема (слитно)
  • Флеш-карта, флеш-диск
  • Флешка
  • Промоакция, промосайт

Кроме того любое слово можно проверить по орфографическому словарю с помощью HTTP-запроса:

http://gramota.ru/slovari/dic/?word=<слово>&all=x

где <слово> – целое слово или его часть, нуждающаяся в проверке правописания.

1 Comment

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

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

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

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

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

1 Comment

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

Introduction to Software Documentation

Recently I was delivering a report on software documentation to my groupmates at the university, who are also employed in IT industry, about the latest trends in our professional area.

The report proved to be interesting. So I decided to extend it by adding some more information, which will be useful for beginners getting started in technical writing.

The presentation contains:

  • What kinds of technical documentation exist
  • What are documentation standards
  • Code documentation tools roadmap
  • Documentation techniques and tools overview
  • Doc styling approaches
  • Some useful recommendations of hep writing

… and so on

The presentation peculiarities:

  • It was prepared for russian audiency, so it has some local-specific information. However, you are free to skip reading it and you will not miss any useful info all the same.
  • The presentation contains two slides describing case studies I was delivering during the report. Do not pay attention to them 🙂

The presentation is available here Introduction to Software Documentation.pdf

Leave a comment

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