Mobile menu

Pages in topic:   [1 2] >
Какой должна быть хорошая документация к программному обеспечению?
Thread poster: _Alena
_Alena
Ukraine
Local time: 04:17
Spanish to Ukrainian
+ ...
Sep 1, 2004

Чтобы не пытаться объять необъятное, скажем, что речь идет о программном обеспечении такого класса, с которым работают переводчики: CAT Tools и другие программы. Т. е. с одной стороны, профессиональные программы, с другой - документация не должна быть какого-то строго установленного типа, можно позволить какие-то отступления.

1. Общие критерии.
Для меня лично самым важным критерием является, чтобы ее хотелось прочитать. Чтобы человек предпочел изучать программу не методом тыка по меню и диалогам, а по документации. Т. е. она должна быть максимально понятной, логичной и легкой в освоении. А потом идут изложение нормальным русским языком и грамотность.

2. Тип документации.
Какой тип документации для вас предпочтительнее: Быстрый старт, Справочник, серия уроков, Manual, интерактивные уроки?

3. Конкретные пожелания.
Например:
- стоит ли говорить более или менее детально (1 стр. и более) об области применения программы, или достаточно только описания функций программы?
- степень детализации: стоит ли описывать такие кнопки, как OK, Cancel, диалоги Save As, Open, или можно предположить, что человек, который собирается работать в этой программе, не первый день видит компютер и со всеми простейшими и стандартными диалогами, кнопками и командами давно знаком, и на чтение их описания он только будет терять время.
- другие

Для меня сей вопрос не философский, а насущный:) Спасибо всем, кто ответит!


Direct link Reply with quote
 

uFO  Identity Verified
South Korea
Local time: 22:17
Korean to English
+ ...
Usable User Documentation" by Edmond Weiss Sep 1, 2004

Обычно при написании технической документации советуют ориентироваться на самого "тупого" пользователя-- уже если он разбереться, то все остальные и подавно. А вообще если есть время и возможность почитайте "Usable User Documentation" by Edmond Weiss, это очень толковый учебник для технических писателей. Я, правда, не знаю, переведен ли он на русский.

Direct link Reply with quote
 

mk_lab  Identity Verified
Ukraine
Local time: 04:17
Member (2004)
English to Russian
+ ...
Вопрос насущный - это как? Sep 1, 2004

1) С точки зрения пользователя, "хорошая" документация - это одно дело: Нужно, чтобы в первых разделах мануала была сжатая и очень понятная квинтэссенция ВСЕХ функций программы. Чтобы было понятно, к какому разделу дополнительной документации следует обращаться по каждому из вопросов. Чтобы документация была негромоздкой и удобной в пользовании.

2) А с точки зрения владельца софта - совсем другое. Нужно, чтобы пользователь понял, какой он идиот, что не умеет до конца воспользоваться грандиозными возможностями предлагаемого программного продукта, которые (возможности) ему при этом должны быть очевидны. Основной вывод пользователя(с точки зрения владельца): нужно купить новую версию программы (дополнительную документацию, обратиться за платной консультацией, приобрести дополнительные программные продукты данного производителя и т.д...). Да, чуть не забыл, этот мануал должен помещаться на 3-4 страничках (зачем жеж задаром платить дармоедам писателям-переводчикам).

3) С точки зрения составителя этой-самой документации, понятное дело:
- Если платят за объем, то нужно писать как можно подробнее, красивее, с большим количеством примеров, и т.д.
- Если платят за рабочее время, то нужно как можно сильнее замутить все сложности работы с софтом, как можно убедительнее показать заказчику необходимость тщательной проработки (желательно с тестированием в учебных центрах) КОНЦЕПЦИИ обучения пользователя работе с программой и т.д....

4) С точки зрения программера:
Все вы идиоты (как пользователи, так и составители документации, а особенно - заказчики). Все-равно вам не понять моих гениальных идей и не простить ничтожность допущенных ошибок. Ну и что, что программа зависает при любой попытке выполнить какую-либо из функций. Ну и что-что она занимает 90% объема любого раздела винта. Это моё гениальное творение - и не фиг вам никому пытаться в нем разбираться-ковыряться...

Так вот, о какой насущности речь идет??? Вы с какой стороны выступаете?


Direct link Reply with quote
 
_Alena
Ukraine
Local time: 04:17
Spanish to Ukrainian
+ ...
TOPIC STARTER
Хоть я и выступаю с двух сторон, которые Вы указали, но я хочу, чтобы все были сыты и целы! :) Sep 1, 2004

И волки, и овцы:) Т. е. довольны:) А вообще-то меня интересует ТОЛЬКО точка зрения ПОЛЬЗОВАТЕЛЯ, что ему удобнее всего и какой документацией он хотел бы пользоваться. Т. е. какую документацию для него лучше всего писать?

mk_lab wrote:
1) С точки зрения пользователя, "хорошая" документация - это одно дело: Нужно, чтобы в первых разделах мануала была сжатая и очень понятная квинтэссенция ВСЕХ функций программы. Чтобы было понятно, к какому разделу дополнительной документации следует обращаться по каждому из вопросов. Чтобы документация была негромоздкой и удобной в пользовании.


А Вы считаете, что содержания и упоминания во вступительной части, что вся информация сгруппирована по темам, так что легко можно найти нужное, недостаточно? И какой тип документации все же предпочтительнее?

2) А с точки зрения владельца софта - совсем другое. Нужно, чтобы пользователь понял, какой он идиот, что не умеет до конца воспользоваться грандиозными возможностями предлагаемого программного продукта, которые (возможности) ему при этом должны быть очевидны. Основной вывод пользователя(с точки зрения владельца): нужно купить новую версию программы (дополнительную документацию, обратиться за платной консультацией, приобрести дополнительные программные продукты данного производителя и т.д...). Да, чуть не забыл, этот мануал должен помещаться на 3-4 страничках (зачем жеж задаром платить дармоедам писателям-переводчикам).


Не, с точки зрения владельца софта мануал должен состоять минимум из 500 страниц, чтобы пользователь понял, за что ему платить такие деньги за программу. В случае необходимости его (мануал) можно использовать с целью самообороны, так как по прямому назначению - весьма затруднительно:) А все остальное - верно:)

3) С точки зрения составителя этой-самой документации, понятное дело:
- Если платят за объем, то нужно писать как можно подробнее, красивее, с большим количеством примеров, и т.д.
- Если платят за рабочее время, то нужно как можно сильнее замутить все сложности работы с софтом, как можно убедительнее показать заказчику необходимость тщательной проработки (желательно с тестированием в учебных центрах) КОНЦЕПЦИИ обучения пользователя работе с программой и т.д....


Ну допустим составителю хочется сделать что-то нужное и приятное. Невероятно, но факт:) А на материальном состоянии это не отражается - все равно платят одно и то ж:)

4) С точки зрения программера:
Все вы идиоты (как пользователи, так и составители документации, а особенно - заказчики). Все-равно вам не понять моих гениальных идей и не простить ничтожность допущенных ошибок. Ну и что, что программа зависает при любой попытке выполнить какую-либо из функций. Ну и что-что она занимает 90% объема любого раздела винта. Это моё гениальное творение - и не фиг вам никому пытаться в нем разбираться-ковыряться...


Так это если пишет один человек. А если работа распределяется на команду, то мания величия соответственно разделяется на всех, сокращаясь до пределов одного нормального человека (специалиста).


Direct link Reply with quote
 
_Alena
Ukraine
Local time: 04:17
Spanish to Ukrainian
+ ...
TOPIC STARTER
А самому тупому (если речь о профессиональной аудитории) понятно, Sep 1, 2004

что за кнопки OK, Cancel, диалоги Open, Save As, команды New, Exit?

uFO wrote:
Обычно при написании технической документации советуют ориентироваться на самого "тупого" пользователя-- уже если он разбереться, то все остальные и подавно. А вообще если есть время и возможность почитайте "Usable User Documentation" by Edmond Weiss, это очень толковый учебник для технических писателей. Я, правда, не знаю, переведен ли он на русский.


Спасибо за книгу, поспрашиваю, есть ли она на русском, хотя меня в данном случае интересует только удобство и польза для пользователя. Сделать "конфетку" конечно хорошо, но невкусную - не хочется.


Direct link Reply with quote
 

mk_lab  Identity Verified
Ukraine
Local time: 04:17
Member (2004)
English to Russian
+ ...
А серьёзно говоря... Sep 1, 2004

А серьёзно говоря, мануал должен быть КЛАССНЫМ! И все понимают, что это означает: небольшой по объему, но объемный по содержанию, изящно и понятно написанный документ, снабженный удобным оглавлением и системой ссылок, удобным многоуровневым Index'ом, и желательно, глоссарием.

Всем все понятно, но по многим причинам (в том числе и перечисленным выше), такие книжечки - редкость.


Direct link Reply with quote
 

uFO  Identity Verified
South Korea
Local time: 22:17
Korean to English
+ ...
Про самых тупых Sep 1, 2004

Все должно быть понятно самому тупому из аудитории для которой Вы пишете.
Обычно информацию рекомендуют разбивать по функциям, которые будет выполнять пользователь, а потом объянять отдельные шаги и результаты(то есть сначала пишете что надо сделать, а потом что должно получиться. Например:
Включение компьютера
1. Нажмите кнопку ХХХ на правой панели.
Компьютер зажжужал и включился.
2. и так далее

Если функции толково названы и индекс и оглавление хорошо составлены продвинутые пользователи видят что им надо читать и пропускают информацию для чайников. Таким образом все получают то что им надо и не теряют время. Можно ставить специальный значок для обозначения информации для "очень умных"
Это я Вам ту книжку вкратце пересказываю (очень рекомендую почитать).

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


Direct link Reply with quote
 

Kirill Semenov  Identity Verified
Ukraine
Local time: 04:17
Member (2004)
English to Russian
+ ...
Остроумной и наглядной :) Sep 1, 2004

Искусство tecnhical writing редкое, тяжелое, но иной раз просто в восторг приводит.

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

Что касается наглядности, то очень симпатичными мне кажутся Tutorials к Традосу -- показывают обычно главное, дают понимание и примеры, не перегружены. А подробности даются в прилагаемых PDF (там, кстати, все не так удачно, многое не сразу понятно).

Но сама идея деления документации на вот такой уровень наглядного Tutorial и классический "завумный" уровень расписывания каждого Cancel мне очень нравится.

Я сам в свое время писал доку к софту (признаюсь, в дурном и казенном стиле), и знаю, какое муторное это дело -- так что искренне сочувствую.


Direct link Reply with quote
 

Nik-On/Off  Identity Verified
Ukraine
Local time: 04:17
English to Russian
+ ...
User Manual Manual Sep 2, 2004

Как-то в сети нашел вот такой документ
The User Manual Manual (How to Research, Write, Test, Edit and
Produce a Software Manual)

Есть заинтересованные лица?


Direct link Reply with quote
 
_Alena
Ukraine
Local time: 04:17
Spanish to Ukrainian
+ ...
TOPIC STARTER
Спасибо! Sep 2, 2004

Кирилл, мне сочувствовать не надо, скорее наоборот:) Тем более что дают довольно большую свободу действий:)
Как мне показалось, все вышесказанное относилось к типу документации Manual. Вот известные мне типы документации к п/о:

1. Manual. Смесь учебника со справочником. Подробное последовательное описание абсолютно всех функций, меню, диалогов программы. Кнопки OK, Cancel, диалоги Open, Save As и им подобные непременно включаются. Как на мой взгляд, самый бесполезный тип документации, так как по нему труднее всего что-либо выучить. Но продвинутым пользователям может пригодиться.

2. Справочник. Думаю, не надо объяснять, что такое справочник. Включает, естественно, описание абсолютно всех функций, меню, диалогов программы. Описание кнопоки OK, Cancel, диалогов Open, Save As и им подобных конечно имеется. Тоже подойдет скорее для продвинутых пользователей.

3. Быстрый старт. Как правило, описывается, как с помощью ассистента или визардов (если таких в программе нет, то просто как) быстро научиться работать с программой. Т. е. как с ходу начать в ней что-то делать. A вот стоит ли здесь описывать всем известные кнопки и диалоги? Как правило, комплектуется мануалом или справочником.

4. Серия уроков. Более подробная, чем "быстрый старт". Описывает от самых простых шагов до самых сложных, как научиться работать с программой. Дается пример, который пользователь должен повторять за автором шаг за шагом. Опять, описывать ли здесь всем известные кнопки и диалоги? Может комплектоваться справочником, или как Миша предлагает, глоссарием.

5. Серия интерактивных уроков. Скриптовая обучающая программка, суть та же, что и в предыдущей. Для солидности комплектуется еще какой-то бумажной документацией.

Так вот, какой тип документации для вас предпочтительнее? По какому хотелось бы учиться? И какой набор документации должна иметь программа?

Миша, спасибо за идею глоссария. А что он должен включать? Понятно, что терминологию по специфике программы. А что еще?

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

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

[Edited at 2004-09-02 10:52]


Direct link Reply with quote
 
_Alena
Ukraine
Local time: 04:17
Spanish to Ukrainian
+ ...
TOPIC STARTER
Заинтересованные лица есть Sep 2, 2004

Nik-On/Off wrote:
Как-то в сети нашел вот такой документ
The User Manual Manual (How to Research, Write, Test, Edit and
Produce a Software Manual)
Есть заинтересованные лица?


А что он из себя представляет и где находится? И конечно же на английском, да?


Direct link Reply with quote
 

mk_lab  Identity Verified
Ukraine
Local time: 04:17
Member (2004)
English to Russian
+ ...
Глоссарий Sep 2, 2004

Elena Malchik wrote:
Миша, спасибо за идею глоссария. А что он должен включать? Понятно, что терминологию по специфике программы. А что еще?


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


Direct link Reply with quote
 

Ekaterina Khovanovitch  Identity Verified
Russian Federation
Local time: 04:17
Member (2005)
Spanish to Russian
+ ...
Быстрый старт и справка. Sep 2, 2004

Освоение программы - процесс длительный, а в некоторых случаях - непрерывный. Но работать-то с ней хочется (а иногда и можно) начать поскорее. Для этого - быстрый старт. Желательно, чтобы он был написан легко и с юмором.
Затем... Мне кажется, освоить какую-либо функцию невозможно, если сразу же, как прочел, не попробовать руками все проделать. Когда я осваивала Ворд, он был еще в шестой версии. Каждый раз перед началом работы выскакивало, заслоняя все, окошко с "советом дня". Когда мне казалось, что совет полезный, я тут же проделывала то, что советовали, на практике. И так запоминала.
Бывает, что надо научиться чему-то конкретному, срочно необходимому. Тогда надо быстро лезть в справку, и она должна быть составлена так, что в ней легко ориентироваться, есть перекрестные ссылки. Скажем, для чего-то надо, среди прочего, использовать кнопку "Копировать", а пользователь такой чайник, что не знает, где она и для чего служит. Дать ссылку. Более опытный пользователь по этой ссылке не пойдет. Таким образом получится пособие, учитывающее интересы разных пользователей.
Текст должен быть предельно ясным. Можно проверять его на знакомых, испытывающих тихий ужас перед компьютером, с которым, тем не менее им приходится работать. Уж если они поймут...


Direct link Reply with quote
 

Nik-On/Off  Identity Verified
Ukraine
Local time: 04:17
English to Russian
+ ...
The User Manual Manual Sep 2, 2004

Elena Malchik wrote:
А что он из себя представляет и где находится? И конечно же на английском, да?


PDF-файл, у меня, на английском


Direct link Reply with quote
 

Sergei Tumanov  Identity Verified
Local time: 04:17
English to Russian
+ ...
важный момент Sep 7, 2004

кроме быстрого старта, без которого просто в современных прогрммах не обйтись, у КАЖДОЙ, повторяю у КАЖДОЙ самой продвинутой функции, должно быть указано А ЗАЧЕМ её, такую навороченную, в программу вставили, чо с ее помощью нужно и можно сделать. небольшой примр полезен но достаточно и описания ситуации из реальной жизни где она может пригодиться.

как сейчас очень живенько помню 93-й год. компьютер с виндовс 3.11
куча окон закрывается, таскается, открывается и сворачивается одним движением мыши.
классная книга издательства BHV/ все подробно написано, глоссарий!!!! - мама не горюй!!!!
и очень простой вопрос радостного пользователя, меня выложившего кучку денег за комп, - а зачем это надо?
первое пособие, в котором я прочитал смысл для чего это надо (много окон сразу), мне в руки попало только через 3 года. я в то время активно рылся в книжных магазинах в хельсинки и в лондоне поэтому выбор пособий в котрых я искал то что мне нужно был большой.


Direct link Reply with quote
 
Pages in topic:   [1 2] >


To report site rules violations or get help, contact a site moderator:


You can also contact site staff by submitting a support request »

Какой должна быть хорошая документация к программному обеспечению?

Advanced search


Translation news in Russian Federation





memoQ translator pro
Kilgray's memoQ is the world's fastest developing integrated localization & translation environment rendering you more productive and efficient.

With our advanced file filters, unlimited language and advanced file support, memoQ translator pro has been designed for translators and reviewers who work on their own, with other translators or in team-based translation projects.

More info »
Anycount & Translation Office 3000
Translation Office 3000

Translation Office 3000 is an advanced accounting tool for freelance translators and small agencies. TO3000 easily and seamlessly integrates with the business life of professional freelance translators.

More info »



All of ProZ.com
  • All of ProZ.com
  • Term search
  • Jobs