Еще думаю про разговоры с CodeFest.
Там был целый квартирник про документацию, но он в итоге свелся в большинстве своем к тест-кейсам. А вот разговоры про это все в кулуарах (в том числе и с настоящим техническим писателем) были хороши.
Первая важная мысль про то, что если можно не документировать - это не надо делать. Лучше скрипт, развертывающий среду тестирования с readme, чем пошаговая инструкция, которую выполняет человек.
Вторая важная мысль про пользу ограничения и заданной структуры. Для английской документации есть simple english - простые слова, простые конструкции, понятные людям с разным уровнем языка. В русском такого формально нет, но чем проще мы пишем - тем лучше читатель это воспринимает.
Людям, как правило, не нужно 3 способа оформления заголовков и 5 - списков. Чем четче струтура и однозначее выразительные средства - тем проще писать документацию. На моей уже прошлой работе мне стало куда проще писать документацию, когда появился четкий шаблон с пунктами, которые надо заполнить.
Мне во всем этом очень нравится идея TeX, когда оформление выносится в отдельный файл, а автор текста заботится только о стурктуре и смысле. Важно, что это заголовок - не важно, как именно он будет выглядеть. Это не так наглядно как WYSIWYG подход ("что видишь, то и получаешь"), зато проще сразу думать о структуре документа.
И третья важная мысль - что документация - это некоторое отображение того, что у заказчика было в голове. И каждое преобразование из головы в текст, а потом обратно в другую голову происходит с потерями. И это тоже надо учитывать.
#менеджерское
Там был целый квартирник про документацию, но он в итоге свелся в большинстве своем к тест-кейсам. А вот разговоры про это все в кулуарах (в том числе и с настоящим техническим писателем) были хороши.
Первая важная мысль про то, что если можно не документировать - это не надо делать. Лучше скрипт, развертывающий среду тестирования с readme, чем пошаговая инструкция, которую выполняет человек.
Вторая важная мысль про пользу ограничения и заданной структуры. Для английской документации есть simple english - простые слова, простые конструкции, понятные людям с разным уровнем языка. В русском такого формально нет, но чем проще мы пишем - тем лучше читатель это воспринимает.
Людям, как правило, не нужно 3 способа оформления заголовков и 5 - списков. Чем четче струтура и однозначее выразительные средства - тем проще писать документацию. На моей уже прошлой работе мне стало куда проще писать документацию, когда появился четкий шаблон с пунктами, которые надо заполнить.
Мне во всем этом очень нравится идея TeX, когда оформление выносится в отдельный файл, а автор текста заботится только о стурктуре и смысле. Важно, что это заголовок - не важно, как именно он будет выглядеть. Это не так наглядно как WYSIWYG подход ("что видишь, то и получаешь"), зато проще сразу думать о структуре документа.
И третья важная мысль - что документация - это некоторое отображение того, что у заказчика было в голове. И каждое преобразование из головы в текст, а потом обратно в другую голову происходит с потерями. И это тоже надо учитывать.
#менеджерское