Сообщений в теме: 10

[LeshaL]

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

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

[kire]

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

К сожалению, необходимых примеров предложить не могу и присоединяюсь к ТС с пожеланиями увидеть фактические примеры удачного документирования внутренних приложений.

[LeshaL]

Я так понимаю вы столкнулись с процессом валидации своих рабочих тулов?

Нет. Я даже не понимаю что такое валидация рабочих тулов. Просто есть в них некая заинтересованность других людей. Пользоваться они ими хотят.

И проблема создать документацию постфактум?

Да нет не проблема. Хочется просто посмотреть на бест-практики. Еще хочется узнать мнение участников форума, так сказать - таргет аудитории, какого рода документация им больше всего по душе.

Если у Вас поставлен процесс, то должны быть какие-то темплейты в помощь создания документации.

О чем вы? Какие процессы, какие темплейты. Все наши тулы написаны под конкретные задачи, и большинство из них изначально не задумывались быть достоянием общественности. Иногда тул - это скрипт на пол-страницы. А его треть - это как раз описание того, что скрипт делает. Мы-то все это знаем и пока тулы внутренние, нам никакие процессы, темплейты никчему. Но если ими делиться с другими командами, то надо как-то их всех описать. У нас даже и такое описание уже есть, и оно по мере появления новых тулов пополняется. Но как показывает практика - описание слишком сухое - люди, которые взяли наши тулы к себе на вооружение задавали мнго вопросов. То, что ребятам в нашей команде кажется очевидным - для других неочевидное. Нам кажется, что такой документации вполне хватает, а другие не понимают.
Вот поэтому и нужны примеры хорошей документации.

[ch_ip]

Да нет не проблема. Хочется просто посмотреть на бест-практики. Еще хочется узнать мнение участников форума, так сказать - таргет аудитории, какого рода документация им больше всего по душе.

Мне больше всего по душе документация типа How-to или в виде FAQ, с примерами на каждый разбираемый сценарий (примеры - обязательно! Для меня лучше примеры без текста под соответствующим заголовком вопроса, чем текст без примера). При изучении продукта и первоначальном использовании мне такой тип документации кажется гораздо более полезным, нежели стандартная документация к большинству крупных продуктов в стиле что есть что. Например, "Есть вот это окно. В нем задаются такие и такие свойства" - это полезно только при доскональном изучении продукта, когда я натыкаюсь на какой-нибудь непонятный чек-бокс и хочется понять, на что он влияет.
Ярких примеров документации к программам мне не вспомнилось, к сожалению. но примеры документации, которая мне нравится:
Краткое руководство по руби: http://www.ruby-lang...ion/quickstart/
Описание, что такое Descriptive Programming в QTP на сайте advancedQTP: http://www.advancedq.../dp-101-slides/
Хотя, с моей точки зрния, во втором примере текста, не несущего смысловой нагрузки, многовато, но это из-за выбранного неформального стиля общения (а-ля Scripting Guys из Microsoft)

[Vasiliy]

В свое время мы делали описание/инструкцию по работе с нашим инструментарием для других офисов.
Описывался весь путь работы, что и как. Документ получался страниц на 30. Потом еще делали отдельно краткое описание по шагам - настройки на странице 4, дальше смотрите страницу 7 и так далее. Мануал для быстрого старта так сказать=)

[LeshaL]

В свое время мы делали описание/инструкцию по работе с нашим инструментарием для других офисов.
Описывался весь путь работы, что и как. Документ получался страниц на 30. Потом еще делали отдельно краткое описание по шагам - настройки на странице 4, дальше смотрите страницу 7 и так далее. Мануал для быстрого старта так сказать=)

Ну раскатать все страниц на 30 задача не стоит. Как раз наоборот, хочется максимально кратко и емко изложить все, что нужно для работы с тем или иным инструментом. Где-то и пол-страницы должно быть достаточно, где-то в 5 страниц хочется уложиться.

Ярких примеров документации к программам мне не вспомнилось, к сожалению. но примеры документации, которая мне нравится:
Краткое руководство по руби: http://www.ruby-lang...ion/quickstart/
Описание, что такое Descriptive Programming в QTP на сайте advancedQTP: http://www.advancedq.../dp-101-slides/

Вот, похоже никто и не может вспомнить примеров хорошей документации. Жаль, жаль. За ссылки спасибо - но это не то. Руби все-таки не тул и это описание не раскрывает и 1% возможностей этого языка. Вторая ссылка - неплохой вариант для презентации, но это не подходит для пользовательской документации.

Просто вариантиов много. Можно оформить
- в виде "книги", с последовательным изложением материала. Плюсы - подробное и взаимосвязанное описание. Минусы - много букв; читать надо полностью, от начала до конца, чтобы понять как с этим делом работать; инфу, которая там есть зачастую можно найти только при помощи функции поиска; сложности при необходимости внесения изменений в доку.
- в виде справочника. Плюсы - лекгий поиск необходимой информации. Минусы - начинать читать можно с любого места(это +), следовательно необходимы кросс-референсы (или накрайняк дублирование инфомации) а это усложняет написание документации и ее сопровождение.
- в виде how-to (FAQ) . Плюсы - ответы на конкретные вопросы, начиная от what is it и заканчивая трюками в каких-то редких ситуациях; легко совпровождать и обновлять доку. Минусы - нет никакой взаимосвязи между частями; упорядоченность или кросс-референсы усложняют написание документации; легко чего-то забыть описать, т.к. нет структуры документа.
- cookbook - некий симбиоз вариантов справочника и FAQ. Набор упорядоченных рецептов. Плюсы - все плюсы этих вариантов. Минусы - все минусы обоих вариантов, за исключением того, что информация изначально упорядочена по каким-то логическим секциям или главам и структурирована.

Вариант кукбука видится мне наиболее приемлимым, хотя и требующим больше затрат на написание, чем ФАК. Единственно, что я смотрю на это со своей колокольни. Мне проще посмотреть примеры, демонстрирующие, как это используется и адаптировать к своему случаю. Кому-то проще прочитать описание как это должно использоваться и что для чего предназначено, а потом придумать как и что надо в конкретном случае.

[novak]

2 LeshaL
А в каком формате подразумевается писать и хранить описание тулов? Возможно, вариант с wiki и совместным редактированием помог бы включить и краткое описание, и примеры - своего рода и справочник, и howto
Не знаю поможет или нет, но можно посмотреть документацию на библиотеку Qt. Пусть это и не описание тулов, но в некотором роде напоминает ваш случай. В ней есть как описание каждого класса, состоящее из краткого изложения предназначения, использования и перечисления функций. Похожей структуры описание модулей. Также есть несколько туториалов и описаний тулов.

[barancev]

http://sqlsus.source...umentation.html
http://sqlsus.source...e.net/demo.html

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

[LeshaL]

А в каком формате подразумевается писать и хранить описание тулов? Возможно, вариант с wiki и совместным редактированием помог бы включить и краткое описание, и примеры - своего рода и справочник, и howto.

А разве это принципиально важно? Представьте, что это вики и есть.

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

Сам QT проект намного-намного превосходит то, что мне надо. Судя по его документации ребята, которые его пишут, уделяют ей немало внимания. Читать и искать что-то в ней приятно и удобно. Не могу оценить техническое содержание. Хотя QT-ную доку как пример я взять не могу, но могу взять их тулзы. Понятно, что я не в теме, хотя и знаю что такое QT.
Давайте посмотрим, вот пример окровенно плохой документации:
D-Bus Viewer
а) необходимо хорошо знать о чем вообще речь, чтобы понять что там написано. Я не понимаю.
б) нет многих деталей, которые интересны пользователю (например, чего может, чего нет).
в) больше на отписку похоже

Вот примеры неплохой документации:
qt3to4
User Interface Compiler (uic)
Хотя и возникают некоторые вопросы в обоих случаях, вполне допускаю, что это именно то, что нужно для каждого из тулов.

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

А вот эта мне понравилась больше всего:
Qt Assistant
Четко. Три уровня - первый чтобы понять что это, что ожидать, и что от меня как пользователя этого тула требуется. На втором - описание того, что тул в принципе умеет и как этим воспользоваться. Третий - для продвинутого использования в частных случаях.

Заметьте, что у всех этих описаний нет определеного единого стиля. Я как раз хочу найти какой-то стиль и его придерживаться.

[LeshaL]

http://sqlsus.source...umentation.html
http://sqlsus.source...e.net/demo.html

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

Отлично, спасибо. Также очень интересна их страничка About. Особенно понравилось в секции Getting started: "type "help" and follow your instincts :)"
Единственно, чего не нашел при беглом просмотре - это версия перла и версии необходимых компонентов, указанных в секции requirements. Как показывает практика с перлом именно в этой области бывают неожиданности.

[novak]

А разве это принципиально важно? Представьте, что это вики и есть.

Просто форма во многом может определить, что и как будет включаться в описание.
В случае с Qt прослеживается интересная закономерность - чем "популярнее" инструмент, тем лучше, по вашим же словам, его описание.
D-Bus Viewer - не слишком широко используемая программка
uic и Qt Assistant - используют часто, но в меру. Потому описание лаконичное, но более-менее подробное.
qmake - основной инструмент для сборки, используется фактически всеми, потому и избыточная подробная документация.

Я к тому, что, вероятно, стоит пойти от необходимости использования той или иной тулзы, а не определять какой-то определённый стиль.