Перед тем, как настраивать наш сайт с документацией и делать его красивым/удобным/эргономичным, нужно снова выполнить небольшую домашнюю работу.
Нет смысла оформлять пустой сайт, поэтому нам стоит позаботиться об его содержании. В рамках этого курса мы с вами изучаем инструменты и процессы docs-as-code и почти не говорим о самой документации (иначе нам пришлось бы задержаться тут на несколько месяцев). Поэтому я предлагаю каждому самому придумать, о чём будет его тестовый портал с документацией.
Советую не заморачиваться очень сильно: продумать концепцию сайта и создать заготовки будущих страниц, наполнить сайт своими тестовыми работами или взять примеры из опубликованной пользовательской документации.
Главное, чтобы мы могли собрать исходники в многоуровневую структуру.
Например, у меня сайт с обучающими материалами, сложенными в два основных раздела: «Онбординг технического писателя» и «Docs-as-code для самых маленьких». Структура сайта будет выглядеть так:
Главная страница // файл index.md
├─ Онбординг тех.писателя // файл onboarding.md
│ ├── Первый урок // файл onboarding/lesson_1.md
│ ├── Второй урок // файл onboarding/lesson_2.md
│ ├── <...>
│ └── Последний урок // файл onboarding/lesson_last.md
└─ Docs-as-code для самых маленьких // файл docs_as_code.md
├── Первый урок // файл docs_as_code/lesson_1.md
├── Второй урок // файл docs_as_code/lesson_2.md
├── <...>
└── Последний урок // файл docs_as_code/lesson_last.md
Если у вас творческий кризис, не переживайте! Я разработал дефолтную схему, чтобы можно было продолжить курс:
Главная страница // файл index.md
├─ Озёра России // файл lakes/index.md
│ ├── Онежское озеро // файл lakes/onega.md
│ ├── Ладожское озеро // файл lakes/ladoga.md
│ └── Байкал // файл lakes/baikal.md
└─ Реки России // файл rivers/index.md
├── Свирь // файл rivers/svir.md
├── Нева // файл rivers/neva.md
└── Ангара // файл rivers/angara.md
В папке docs проекта создайте папки lakes и rivers, внутрь которых сложите md-файлы озёр и рек. В сами файлы добавьте краткие описания объектов (не забудьте разметить их с помощью маркдауна). Также в папках lakes и rivers создайте два главных файла разделов, которые будут называться
index.md (да, тоже индекс.мд, только вложенные в папки разделов). Внутри можете написать какой-нибудь обобщающий текст по своему усмотрению.Не забудьте, что все изменения мы делаем по классическому флоу с помощью гита (нужно отколоть новую ветку task-3-add-files, закоммитить изменения, отправить их на сервер, создать и пулл-реквест и влить изменения в main).
Фух, поздравляю, теперь мы готовы оформлять сайт! Если у вас всё получилось, ставьте рукопожатие в реакциях к этому посту 🤝
Если что-то не получилось, приходите в комментарии.
#docsascode #практика