Общие черты документации кода

Edit me

Документация кода описывает то, как разработчики будут использовать ваши API и другие сервисы для достижения своих целей. Такая документация часто включает актуальные части кода и конфигурации различных сервисов. Это «задачи», которые будут более общими для документации конечных пользователей.

Документация кода могут иметь общие разделы или характеристики (хоть при этом и не имея одинакового названия).

Разработка шаблона с проработанной структурой, поможет собрать нужную информацию для проработки документа с описанием кода.

‍👩‍💻 Практика: сравниваем документацию с описанием кода

Документация часто содержит такие разделы:

описание сценария - отвечает на вопрос «Почему?»;
результаты - цели или демонстрация решения;
обзор решения - исчерпывающее описание решения;
целевая аудитория - предположения о том, для кого сделана документация, уровень квалификации разработчика;
предварительные условия - требования к программно-аппаратному обеспечению, конфигурациям необходимым для корректной работы;
шаги - задачи, достигающие решения, часто представляются в виде разделов. Шаги показывают порядок сборки, работающего решения, построение кода из кусочков по мере необходимости (как, например, Lego);
реальные примеры - примеры или информация, добавленная в шаги с понятным описанием;
пояснения - концептуальные объяснения, заметки, сноски.
встроенные комментарии - объяснения внутри кода о том, что происходит;
заключение, следующие шаги - завершение, пример полностью готового кода, указания на следующие логические шаги, ссылки на соответствующие разделы.

Ниже приведены образцы такой документации. Можно выбрать пару проанализировать их, чтобы увидеть, сколько вышеперечисленных общих разделов и характеристик получится найти.

🔙

Go next ➡