Должны ли программисты уделять внимание написанию документации? Это на первый взгляд небольшой, но довольно важный вопрос. Помимо программ и данных, программное обеспечение также включает документацию. Более того, если программист умеет только писать программы и не может должным образом и изящно описать свои идеи в документации, то он поистине становится «код-фермером».
Важность написания документации
В отраслях, связанных с программным обеспечением, будь то в школе или на рабочем месте, все, возможно, замечали, что помимо написания программ и рисования проектных диаграмм,есть ещё одна важная задача: написание документации.Почему нужно писать документацию? Потому что нам нужно показать то, что мы сделали, — не только коллегам, но и сотрудникам на других должностях и даже пользователям. Если мы умеем только писать программы и не можем должным образом и изящно описать свои идеи в документации, то мы поистине становимся «код-фермерами».
Я заметил, что очень немногие из окружающих меня коллег умеют писать высококачественную документацию. Господин Кай-Фу Ли, впредисловии к «Волне»,сказал: «Я знаю многих выдающихся инженеров, но выдающиеся инженеры с сильными навыками повествования, среди тех, кого я знаю, крайне редки».
Действительно, среди знакомых мне коллег очень немногие умеют ясно выражать свои идеи в документации.
- Мы каждый день отправляем и получаем много электронных писем. Я внимательно присмотрелся и обнаружил, что во многих письмах либо неуклюжие фразы, либо много опечаток, либо неправильно употреблены или пропущены знаки препинания. Во многих случаях письмо можно истолковать по-разному, из-за чего людям неясно, что именно оно пытается выразить, что сильно снижает эффективность работы.
- Помимо кода, проекты также содержат большое количество документации. Когда я открываю большинство документов, первое, что я чувствую:Беспорядочная вёрстка, неправильное форматирование, корявые предложения и повсюду опечатки.С первого взгляда видно, что автор не отнёсся к документу серьёзно, а его способность выражать и организовывать предложения также слаба.
- Во время обсуждений в команде проекта почти все говорят о том, как хорошо писать программы, но никто не упоминает, как улучшить написание документации. Похоже, все согласны с тем, что обязанность разработчика — хорошо писать программы, а всё остальное второстепенно.
Традиционное определение компьютерного программного обеспечения таково: программное обеспечение — это другая часть компьютерной системы, которая взаимозависима с аппаратным обеспечением. Программное обеспечение включает полную совокупность программ, данных и связанной документации.Обратите внимание, что здесь упоминается «связанная документация». Если документация написана плохо, программное обеспечение нельзя считать превосходным. Фактически бывают случаи, когда функции программного обеспечения работают исправно, но сбои происходят из-за проблем с документацией.
Вообще говоря, в процессе разработки программного обеспечения основные документы, задействованные на разных этапах, показаны на следующем рисунке:
Видно, что на разных этапах разработки программного обеспечения необходимо писать разные документы. На этапе планирования необходимо писать документы детального проектирования, документы плана модульного тестирования и документы плана интеграционного тестирования; на этапе разработки эти же документы по-прежнему нужны, но уже в виде пересмотренных версий, поскольку в ходе фактической разработки мы можем обнаружить необоснованные или плохо продуманные части предыдущего проектирования, что требует изменения более ранних документов; на этапе тестирования необходимо писать отчёты о модульном тестировании, отчёты об интеграционном тестировании и отчёты о системном тестировании; на этапе выпуска программного обеспечения необходимо писать руководства по установке, руководства пользователя, руководства по обновлению и т. д. Эти документы в основном предназначены для специалистов поддержки на местах и пользователей, поэтому они должны быть написаны понятным языком и не должны содержать никакой двусмысленности; иначе останется только ждать жалоб от пользователей.
Чтобы писать хорошую документацию, сначала нужно исправить одно заблуждение: будто документация не важна. Документация должна стоять на одном уровне с программами.
Как писать высококачественную документацию?
Итак, как же нам писать высококачественную документацию? Думаю, можно начать со следующих аспектов:
- Измените представление о том, что документация второстепенна. В повседневной работе серьёзно относитесь к каждому документу, который пишете.
- В электронных письмах точно выражайте то, что хотите сказать. Перед отправкой письма проверьте, полон ли его текст, нет ли опечаток и достаточно ли гладко построены предложения.
- При написании документов строго следуйте шаблону, заданному проектной командой. После завершения документа запустите проверку грамматики, чтобы исправить опечатки и грамматические ошибки. Как правило, под предложениями с грамматическими ошибками появляется зелёная волнистая линия. Перед сдачей документа ещё раз прочитайте весь документ целиком, чтобы проверить, нет ли пропусков или недочётов.
- В свободное время можно читать книги или статьи, которые улучшают языковую выразительность и навыки письма, и наблюдать, как другие ясно излагают свои мысли. Например, регулярное чтение блогов выдающихся блогеров на CSDN — хороший способ улучшить свои навыки письма.
В целом, как и в других делах, написание документации также отражает отношение человека. Написание качественной документации может не только улучшить ваш личный имидж (если вы прочитали хороший документ, разве вы не станете лучше думать об авторе?), но и улучшить имидж продукта в глазах клиентов. При таком анализе действительно стоит приложить больше усилий к написанию документации.
Чтобы хорошо что-то делать, нужно стараться во всех аспектах. В процессе разработки программного обеспечения важно писать хороший код, и так же важно ясно выражать свои мысли в документации. «Код» и «документация» — как левая и правая руки человека; обе должны развиваться сбалансированно, и нельзя сосредотачиваться только на одной.
От:CSDNАвтор: Чжоу Чжаосюн