Начните с README.md

Я твердо верю в Readme Driven Development. Эта парадигма проста:

Сначала напишите Readme.

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

В соответствии с этим, написание высокоуровневого README.md — это то, как я начал discord-server-info!

Давайте посмотрим, как я структурировал наш README.md:

Заголовок

Вот первые три строки файла:

# `discord-server-info`

> Explore Discord server data and statistics
Войти в полноэкранный режим Выйти из полноэкранного режима

Это следует стандартной схеме, которой я обычно следую для любого README.md, который я создаю:

  • первая строка — это h1 название проекта.
    • поскольку название проекта совпадает с названием репозитория, я обернул его в блоки инлайн-кода
  • следующая строка — это блок-цитата с однострочным описанием проекта.

Мне нравится этот шаблон, потому что он сразу же устанавливает две ключевые части информации для читателя:

  • как ссылаться на этот проект
  • является ли этот проект актуальным для них.

Читатель не должен заходить слишком далеко в наш файл, чтобы узнать что-либо из этого.

Введение

Следующий раздел после заголовка — Introduction, который дает высокоуровневый обзор проблемного пространства discord-server-info.

По сути, это сжатая версия вводного поста из этой серии.

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

Технический обзор

Последний раздел — Технический обзор. Если во введении говорится о том, что и почему, то в техническом обзоре — о том, как.

Это почти идентично посту о техническом обзоре высокого уровня из этой серии.

Поскольку у меня в голове уже есть идея, как мы можем построить этот проект для достижения наших целей, я изложил в этом разделе то, как это выглядит на высоком уровне.

Это позволит потенциальным участникам понять, в каком направлении мы движемся, и общую структуру проекта.


Я мог бы включить в Readme гораздо больше информации, но не стал этого делать, например, конкретные детали того, как должен быть собран каждый пакет, или некоторые технические трудности, с которыми мы потенциально можем столкнуться.

Вместо этого мы будем относиться к Readme, как ко всему остальному в репозитории, и работать над ним.

Когда мы достигнем момента, когда мы будем готовы увеличить масштаб одного из пакетов и реализовать его, я добавлю в Readme высокоуровневый обзор того, как это выглядит.

Это позволит нам получить преимущества Readme Driven Development, не забегая слишком далеко вперед.

Оцените статью
Procodings.ru
Добавить комментарий