Перейти к основному содержимому

Стандарты оформления документации

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

Правила именования файлов​

  • Лабораторные работы: lab-XX-topic.md или labXX/index.md (где XX - номер работы).
  • Курсовые работы: XX-topic.md (где XX - порядковый номер в курсе, например 01-rp-op-design.md).
  • Используйте kebab-case для названий файлов и папок.

Обязательные секции​

Каждый файл должен начинаться со следующей структуры:

# [Название работы]

## Для кого этот документ
- Студентам X семестра
- Требования: [знания, навыки]
- Необходимое ПО: [список]

## Цель работы
[Краткое описание цели]

## Что нужно знать перед началом
- [Ссылка на теорию]
- [Ссылка на предыдущую работу]

## Где найти файлы проекта
Все файлы находятся в папке: `[путь]`

В конце каждого файла должны быть:

## Чеклист выполнения
- [ ] Пункт 1
- [ ] Пункт 2

## Часто задаваемые вопросы (FAQ)
**Q: Вопрос?**
A: Ответ.

## Связанные материалы
- [Ссылка 1]
- [Ссылка 2]

Шаблон для Лабораторной работы​

---
id: labX
title: ЛР №X [Название]
slug: /computer-organization/labs-sem7/labX
---

# ЛР №X [Название]

[Краткое описание темы работы]

## Контекст
(Опционально) Краткое введение в тему лабораторной работы, объяснение её места в курсе.

## Цель работы

[Четко сформулированная цель работы]

## Объект изучения
(Или "Объекты изучения" если несколько)

- [Объект 1]
- [Объект 2]

## Планируемые результаты обучения

После выполнения этой работы студенты должны уметь:

- [Навык 1]
- [Навык 2]
- [Навык 3]

## Исходные файлы лабораторной работы

[Описание файлов, если есть. Может содержать ссылки на листинги в приложении]

## Подготовка к лабораторной работе

Для выполнения лабораторной работы необходимо изучить по материалам лекций и предложенной литературе:

1. [Тема 1]
2. [Тема 2]
3. [Тема 3]

## Вопросы для самоконтроля
(Опционально)

1. [Вопрос 1]?
2. [Вопрос 2]?

## Чеклист выполнения
(Опционально)

- [ ] [Пункт 1]
- [ ] [Пункт 2]
- [ ] [Пункт 3]

## Порядок выполнения лабораторной работы

### Часть 1. [Название части]

1. [Пункт задания 1]
2. [Пункт задания 2]

### Часть 2. [Название части]

1. [Пункт задания 1]
2. [Пункт задания 2]

## Отчетные материалы

Отчетные материалы должны содержать:

1. Цель лабораторной работы.
2. Материалы, связанные с подготовкой к работе, включая теоретическую часть.
3. Информацию по выполнению каждого пункта задания. Причем в отчете должны содержаться выполняемые Вами действия, наблюдаемые результаты и Ваши объяснения.
4. [Дополнительные требования]
5. Краткое заключение.

## Защита лабораторной работы
(Или "Защита работы")

[Описание процедуры защиты или примерные задания для защиты]

## FAQ
(Опционально)

**Q: [Вопрос]?**
A: [Ответ]

## Дополнительные материалы

- [Ссылка 1]
- [Ссылка 2]

## Приложения
(Если есть листинги кода, рисунки, таблицы)

### Приложение А

[Описание приложения]

![Рис. X.1 – Название рисунка](image/path/to/image.png)

**Таблица X.1 Название таблицы**

| Колонка 1 | Колонка 2 |
|-----------|-----------|
| Значение 1 | Значение 2 |

### Приложение Б

**Листинг X**

**Исходный файл программы filename.s**

```assembly
// код программы

Или с именем файла в заголовке:

Листинг X. Текст программы filename.s

// код программы

Важно:

  • Заголовок должен начинаться с ### Листинг и содержать номер (например, ### Листинг 1 или ### Листинг 2. filename.s)
  • После заголовка может быть описание с именем файла (рекомендуется формат: **Исходный файл программы filename.s**)
  • Code block должен следовать сразу после заголовка или описания
  • Язык программирования определяется автоматически из класса code block (например, language-asm, language-assembly, language-c)

Примечание: Кнопка скачивания листингов добавляется автоматически на все страницы. Не нужно добавлять компонент вручную.


**Важно о frontmatter (блок с тройными дефисами в начале файла):**

- **Frontmatter опционален** — если его не использовать, Docusaurus автоматически сгенерирует `id` и `slug` из пути к файлу
- Если frontmatter используется, **НЕ УДАЛЯЙТЕ** тройные дефисы (`---`) в начале и конце блока
- **НЕ ДОБАВЛЯЙТЕ** лишние пробелы в строках между дефисами
- **НЕ ИЗМЕНЯЙТЕ** содержимое между дефисами без необходимости (строки с `id:`, `title:`, `slug:`)
- Если frontmatter поврежден — сайт может не собраться
- **Рекомендация:** Для новых файлов можно не использовать frontmatter, Docusaurus автоматически определит метаданные из структуры папок

## Шаблон для Курсовой работы

```markdown
# Курсовая работа: [Название]

## Для кого этот документ
...

## Введение
Цель, задачи, требования.

## Теоретические основы
...

## Практическая часть
Пошаговое руководство.

## Примеры реализации
...

## Чеклист выполнения
- [ ] ...

## FAQ
...

## Приложение
(Если есть листинги кода)

### Листинг 1
**Исходный файл программы example.s**

```assembly
// код программы

Или с именем файла в заголовке:

Листинг 2. Текст программы example.s​

// код программы

Важно:

  • Заголовок должен начинаться с ### Листинг и содержать номер (например, ### Листинг 1 или ### Листинг 2. filename.s)
  • После заголовка может быть описание с именем файла (рекомендуется формат: **Исходный файл программы filename.s**)
  • Code block должен следовать сразу после заголовка или описания
  • Язык программирования определяется автоматически из класса code block (например, language-asm, language-assembly, language-c)

Примечание: Кнопка скачивания листингов добавляется автоматически на все страницы. Не нужно добавлять компонент вручную.


## Связанные материалы

- [Как внести вклад](./getting-started.md) — если вы еще не знакомы с процессом создания Pull Request
- [Работа с файлами](./working-with-files.md) — для работы с листингами и файлами для скачивания