International Project Engineering изнутри

Документация, а какой она должна быть?

В сентябре 1987 года Майкрософт выпустил Microsoft Bookshelf – коллекцию популярных книг и справочников на компакт-диске. Это был один из первых продуктов, который был выпущен на компакт-диске.

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

Одновременно с локализацией программ вся эта масса знаний переводится на другие языки. Зачастую, командам локализации вовсе не очевидно нужно ли это делать. Но мы делаем; переводим, переводим, переводим…

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

Неужели наше программное обеспечение сложнее чем здоровье и воспитание ребенка?!?

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

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

Published Wednesday, September 06, 2006 1:55 PM by Aram

Comment Notification

If you would like to receive an email when updates are made to this post, please register here

Subscribe to this post's comments using RSS

Comments

 

VladislavA said:

Печатное руководство типа Getting started на 20-30 страниц.

Полное печатное руководство на 500-1000 страниц.

Переводы нужны. Сам я не испытывают трудностей с чтением En-документации, но вижу вокруг много людей, которые эффективнее работают с русской документацией.

Хотелось бы, чтобы в TechNet и MSDN была вся документация. Сейчас же даже содержание сайта TechNet и  содержание TechNet subscription media - несинхронизированы. И поиск нужен нормальный, не хуже гугл-качества.

И содержание документации должно действительно оперативно (макс. 1 неделя) модифицироваться.
September 7, 2006 2:09 AM
 

Raiker said:

Я все понимаю - и сложность современных проектов, и их богатые возможности и прочее и прочее. Но делать Windows SDK размером на 2 ГБ это, по-моему, все же перегиб.
September 7, 2006 12:54 PM
 

Aram said:

Кстати про SDK, а на сколько полезно будет переводить подобного рода документацию?

На мой взгляд, это очень непростая задача, т.к. большинство разработчиков используют английскую терминологию, что приводит к низкой используемости переводной документации, в силу не строгого соответствия терминов в английском и, например, в русском языках.
September 7, 2006 1:14 PM
 

MoGol said:

Задумался о том как работаю с продуктом сам (с точки зрения админа, а не разработчика). Обычно, Getting Started просто не читается, точнее читается, если возникли проблемы на тестовой системе. Причем его достаточно в электронном виде.

Руководство - не знаю, подробное описание настроек - эл. справка, а любимой книгой по WinServer является Рассел/Кроуфорд и др. Там дается не только "как", но и "почему так", читать такую книгу удобнее на диване, и если она будет в эл. форме, то только как дополнение к печатной, т.к. одолеть её за экраном это нереально. И читать её приятнее на родном языке (если она грамотно переведена). Справка д.б. на языке системы.

Резюме - в печатном виде книги по идеологии работы с системой, в эл. справки по интерфейсу, по ком. строке, различные виды How-To, плюс эл. версия книги по иделогии, чтобы быстрее искать нужное место.

November 10, 2006 4:36 AM
 

Aram said:

А насколько полезен сайт Office Online?

Я сам только недавно стал им пользоваться для создания документов, не относящихся к моей работе. Для рядового пользователя там есть много полезных и простых примеров решений (шаблонов), которые экономят много времени на создании типовых документов.

Мы используем этот сайт и для серверных продуктов, но, честно говоря, я не знаю насколько он полезен для администраторов систем. Должен ли он быть более техническим, или содержать информацию маркетингового характера, особенно для серверных продуктов? У нас ведь есть база знаний, TechNet и т.п.?

November 10, 2006 11:57 AM
 

Vladislav Artukov said:

В свое время я очень удивился, когда совершенно случайно обнаружил раздвоение KB. Часть KB articles по Office была только на Office Online. И их СОВСЕМ не было в TechNet subscription!

По моему мнению, такая местечковость сильно вредит делу. Есть один портал TechNet, пусть он останется одной точкой входа в Knowledge Base. (Поиск по KB - это предмет отдельного разговора.)

November 17, 2006 8:18 AM
 

Yury said:

Office Online полезная и очень нужная штука.

Периодически захожу посмотреть что есть, так... для повышения образования.

А вобще, документации много не бывает. Бывает только плохо с поиском в этой документации и удобству выхода на нее из продукта.

February 9, 2007 11:28 PM
 

Yury.Radchenko said:

Office Online очень полезен. Сам периодически захожу туда чтобы узнать что-то новенькое.

А документации не бывает много. Быает плохой поиск и плохая привязка к возникшей проблеме (вопросу).

February 9, 2007 11:52 PM

Leave a Comment

(required) 
(optional)
(required) 

  
Enter Code Here: Required
Submit

This Blog

Syndication

News

Информация на данном сайте предоставляется "КАК ЕСТЬ" без каких-либо гарантий и передачи прав. Мнения, высказанные здесь, являются отражением моего личного взгляда, а не позиции работодателя.

© 2009 Microsoft Corporation. All rights reserved. Terms of Use  |  Trademarks  |  Privacy Statement
Microsoft
Page view tracker