Форум Сообщества Аналитиков

×


Эффективная инженерная (и не только) документация(Прочитано 30327 раз)
Я продолжаю по дружески удивляться :), что человек, который собирается вести тренинг "эффективная инженерная документация" продолжает писать статьи, которые:
а) не имеют оглавления
б) не имеют описания целей
в) представлены в слабо читабельном формате
г) не поддерживают отсылку к отдельным абзацам
д) не поддерживают комментирование и обсуждение отдельных абзацев, высказываний
е) не поддерживают внесение правок и создание новых версий
ж) имеют бестолковый урл
з) имеют ошибки в title
и) практически не имеют гиперссылок
« Последнее редактирование: 24 Июня 2008, 16:05:41 от Денис «Майевтик» »



Я продолжаю по дружески удивляться, что человек, который собирается вести тренинг "эффективная инженерная документация" продолжает писать статьи, которые:
а) не имеют оглавления
б) не имеют описания целей
в) представлены в слабо читабельном формате
г) не поддерживают отсылку к отдельным абзацам
д) не поддерживают комментирование и обсуждение отдельных абзацев, высказываний
е) не поддерживают внесение правок и создание новых версий
ж) имеют бестолковый урл
з) имеют ошибки в title
и) практически не имеют гиперссылок


А в чём противоречие? Разве в этом всём заключается эффективность?
greesha.ru

Реальность - это убийство прекрасной теории бандой мерзких фактов. (Роберт Гласс)



А в чём противоречие? Разве в этом всём заключается эффективность?
Эффективный документ эффективен по структуре, содержанию и оформлению. Задачи документа -- обеспечить коммуникацию информации и предоставить возможность обсуждения, отсылки к и развития.
« Последнее редактирование: 24 Июня 2008, 16:02:09 от Денис «Майевтик» »



Денис, принял к сведению твое удивление, но замечаний по существу, к сожалению не увидел, вероятно, эта заметка не прошла твой входной контроль по формальным признакам :)
Мне читать глазам больно. Шрифт мелкий, полей нет, абзацы выделены кое-как, html-списки не используется, вместо них "печатная машинка style".

А про существо -- текст из серии "вода мокрая, небо синее". Цели заяви сначала, тогда можно будет рецензировать.
« Последнее редактирование: 24 Июня 2008, 16:02:15 от Денис «Майевтик» »



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

Эффективность, в общем случае, это степень соответствия поставленной цели. Если автор документа ставит целью "обеспечение коммуникации информации", то, наверное, всё это нужно...

А если цель - заострить внимание на высокой неопределённости проектной деятельности (что прекрасно удалось), да ещё уложиться в три страницы, то все эти навороты в зоопарке только мешают.

Разумеется, imho, как всегда.
« Последнее редактирование: 24 Июня 2008, 16:02:20 от Денис «Майевтик» »
greesha.ru

Реальность - это убийство прекрасной теории бандой мерзких фактов. (Роберт Гласс)



Эффективность, в общем случае, это степень соответствия поставленной цели. Если автор документа ставит целью "обеспечение коммуникации информации", то, наверное, всё это нужно...
Это не про "если". Это обязательное условие создания любого рабочего документа. "Если" автор таких целей не ставил, то документ не стоит и читать.

Цитировать
А если цель - заострить внимание на высокой неопределённости проектной деятельности (что прекрасно удалось), да ещё уложиться в три страницы, то все эти навороты в зоопарке только мешают.
Я не понимаю, как наличие вменяемого TITLE, позволяющего, например, добавлять статью в закладки и делиться с другими, может чему-то помещать.
« Последнее редактирование: 24 Июня 2008, 16:02:26 от Денис «Майевтик» »



Это не про "если". Это обязательное условие создания любого рабочего документа. "Если" автор таких целей не ставил, то документ не стоит и читать.

А это уже зависит от целей, которые ставит перед собой читатель. :)
В общем, благодаря этой статье развернулась дискуссия о целеполагании - чем не польза?
greesha.ru

Реальность - это убийство прекрасной теории бандой мерзких фактов. (Роберт Гласс)



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

'дискуссия о целеполагании' - сказано сильно.

то Денис «Майевтик»: можете привести ссылку на рекомендуемый_вами вариант 'оформления' документов? например, ваш документ, как образец.



'дискуссия о целеполагании' - сказано сильно.
Григорий, это последняя статья в цикле, но до нее было множество других, потому и разговорились о целеполагании.
Посмотрите на ответ Дениса, он именно об этом и говорит, о целеполагании, назначении документа



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

О форме можно спорить бесконечно долго, но imho, офрмление статьи, послужившей поводом для спора, вполне соответствет и целям автора, и целям сообщества: автор изложил свою идею и вынес её на широкое обсуждение на форум uml2.ru.

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

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

Единственная претензия, с которой соглашусь - тэг title кривой, движок не мешало бы подправить. Но, опять же, это не смертельно.
greesha.ru

Реальность - это убийство прекрасной теории бандой мерзких фактов. (Роберт Гласс)



2 тысячи слов, 10 тысяч знаков, 7 страниц и 3 картинки, на которые ушло явно не 5 минут работы - это не запись в блоге. Поверьте мне, заядлому блоггеру с 4 дневниками и 6 годами опыта.



Красота мира - в многообразии.

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

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

Для инженерной документации есть, конечно, определённые стандарты, за которыми стоит здравый смысл и многолетний опыт Идущих по граблям (в армии вообще говорят: "каждая строка Устава написана кровью"). Но не случайно ведь возникла методология экстремального программирования с её минималистским стилем (нарисуй на бумажке, а бумажку выкинь) - мир меняется, и в стандарте всего не опишешь.
greesha.ru

Реальность - это убийство прекрасной теории бандой мерзких фактов. (Роберт Гласс)



Мне тут в голову очередная ехидная мысль пришла. :)


Титульный лист =i=
О необъятии необъятного

Лист изменений =ii=
Версия: 0.1 Изменено: К. Прутков Дата: март 1859 Описание: начальная версия

Пустая страница =iii=
This page intentionally left blank

Оглавление =iv=
Глоссарий .... 1
Введение .... 2
1. О необъятии необъятного .... 3
Связанные документы .... 4
Индекс .... 5

Глоссарий =1=
Необъятное - то, что невозможно объять

Введение =2=
Сие произведение констатирует тот факт, что объять необъятное невозможно.

1. О необъятии необъятного =3=
Никто не обнимет необъятного.

Связанные документы =4=
Проект о введении единомыслия в России
http://www.prutkov.org.ru/lib/sb/book/2091/page/0

Индекс =5=
В
Введение 4
Е
Единомыслие 4
Н
Никто 3
Необъятное 2,3,4
П
Проект 4
Произведение 2
Р
Россия 4
Ф
Факт 2
greesha.ru

Реальность - это убийство прекрасной теории бандой мерзких фактов. (Роберт Гласс)



Григорий, супер! :)

Я склоняюсь к твоему мнению по поводу статьи Boatmana, все-таки это творческая концепция, хотя вижу и логику Дениса.




 

Sitemap 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19