Blogs

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

  • Comments 8
  • Likes

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

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

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

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

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

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

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

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

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

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

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

    И содержание документации должно действительно оперативно (макс. 1 неделя) модифицироваться.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Your comment has been posted.   Close
Thank you, your comment requires moderation so it may take a while to appear.   Close
Leave a Comment