Вообще, самое сложное для режиссера — сохранить незамыленный взгляд. Это касается абсолютно всех режиссеров и абсолютно всех фильмов в мире. Ну вот представьте себе: вы придумали идею, написали сценарий, раскадровку сделали, сняли, смонтировали, музыку наложили — короче, к моменту финального монтажа свой собственный фильм вы видели тысячу раз. И вот тут очень важно не вырезать лишнего, того, что вам представляется абсолютно ясным и логичным. Надо подумать, будет ли эта конкретная склейка понятна зрителям. Если они чего-то не поймут — все, привет. Это вещи, которым учишься в процессе. Учишься объективно оценивать то, что сделал, учишься смотреть материал чужими глазами. Это страшно важная вещь для режиссера — уметь смотреть отснятый материал. Это искусство плюс дисциплина.
Имхо, эти слова должны запомнить программисты, которые пытаются писать документацию к своей программе.
Еще по поводу документации одно собственное наблюдение выскажу: если повезет, то можно сразу написать хорошую программу, которая будет удовлетворять пользователей (в основном за счет того, что разработчик сам долгое время был ее пользователем). Но вот написать сразу хорошую документацию не получится. Никак. Вообще.
Основное преимущество софта перед документацией - если что-то непонятно, то софт всё равно используют, пробираются, оставляют фидбек. А если не ясна документация - её просто не читают. Нет основы для улучшения :-)
ОтветитьУдалитьУ нас, на мой взгляд, бестолковая, непонятная и слишком объёмная документация. Но ни один заказчик ещё не выскзаал по этому поводу замечаний. А знаешь, почему? Потому, что её никто не читал.
Научиться пользоваться LiveWriter-ом без документации можно, даже Word-ом можно. Настраивать MSSQL и уж тем более Oracle без документации -- это фантастика. Если у меня будет выбор программных инструментов с разным уровнем документации, я предпочту тот, у которого она лучше.
ОтветитьУдалитьВысказывание "программисты документацию не читают" мне в последнее время очень сильно не нравится. Имхо, программисты, которые документацию не читают, и тесты нормально написать не могут. Что выливается в увеличение времени на выпуск продукта и в снижение его качества.
>У нас, на мой взгляд, бестолковая, непонятная и слишком объёмная документация. Но ни один заказчик ещё не выскзаал по этому поводу замечаний. А знаешь, почему? Потому, что её никто не читал.
Да ладно тебе :) "У нас" -- это уже очень объемное понятие. Нашу документацию по AAG и читают, и перечитывают, и жалуются, и ляпсусы находят, и исправлять заставляют. И даже внедрять без документации отказываются (что правильно).
Более того, я сам уже не помню всего, что AAG умеет делать. Буквально в конце прошлой неделе об одном важном умении мне напомнили, указав точный раздел документации, который я сам и написал. У меня был шок. Я уже нихрена не помню, а в документации все подробно зафиксировано, даже с примерами.
Ещё часто умиляет Javadoc-подход (Не только к Яве применим, конечно) - вот тут у нас есть API-reference. Точка. Ни примеров, ничего. Если библиотека небольшая, то ничего, но если классов 50 с наворотом абстракций?
ОтветитьУдалитьДокументация, да, проблема. В неоплачиваемом Open-Source коде особенно явно.
В одном проекте, например, всё руки не доходят перевести русские комментарии на английские. При этом, так вышло, что большинство пользователей библиотеки по-русски не говорят :). У них переводчик Гугла работает за нас.
>вот тут у нас есть API-reference. Точка. Ни примеров, ничего.
ОтветитьУдалитьА еще я когда-то читал мнение, что unit-тесты как раз могут использоваться в качестве примеров. Высказанное кем-то вроде Дейва Томаса. После чего, похоже, это дело взяли за правило.