На прошлой лекции мы с вами обсудили то где писать код и текст. Как писать код вас научат на других курсах. Однако на многих из них от вас будут требовать написания документации или отчетов о проделанной работе. И вот об этом мы сегодня с вами поговорим.
Сегодня практически везде где упоминается слово документация я буду подразумевать как непосредственно документацию, так и все возможные отчеты(описания проделанной работы, научные статьи, курсовые, etc.).
В ходе развития любого вашего проекта, он начнет обрастать разнообразной документацией. Если в начале она будет заключаться в ваших комментариях внутри кода, то при увеличении количества участников задействованных в проекте вам понадобиться научиться как передавать знания по “горизонтали”(для ваших коллег и смежников), так и по “вертикали”(для онбординга новичков или более детального погружения руководства в непосредственно вашу деятельность).
Хорошая документация поможет вам решить многие вопросы
В свою очередь плохая документация может усложнить и даже навредить работе вашей команды.
Так что же такое “хорошая документация”? Однозначного ответа нет(и, на мой взгляд, не может быть). Одним людям нравится предельная строгость LaTeX-а, других она отталкивает. Одним важно, что бы документация описывала максимально дотошные элементы “систем”(что бы под этим словом не подразумевалось — языки программирования, программное обеспечение, etc.), другие хотят уметь быстро высокоуровнево понять смысл и затем по исходникам(e.g. коду) разобраться в теме глубже.
Поэтому я не назову вам “ультимативный гайд по лучшей документации”. Оставьте это для кликбейтов. Но постараюсь описать правила которые, как минимум, не навредят вам, а чаще всего улучшат их.
Для некоторых видов документации существуют общепринятые стандарты. Например каждый proposal в стандарт C++ должен удовлетворять стандарту.
Поэтому в начале ответьте на вопрос “Нужно ли мне придерживаться общепринятого стандарта?”. Если ответ “да”, то при первом написании старайтесь придерживаться его максимально. Некоторые сообщества программистов славятся своим непринятием новичков, а те, что нет, будут складывать о вас первое впечатление именно по тому как вы придерживаетесь внутренних правил.
Общие правила являются следующими