Чому документація OpenBSD така хороша?

Автор: Solène, 18 серпня 2022 р. Теги: #openbsd #documentation

Коментарі щодо Fediverse/Mastodon

Операційна система OpenBSD відома своєю безпекою, але також має точну та чудову документацію. У цьому тексті я спробую зрозуміти, що робить документацію OpenBSD такою чудовою.

Веб-сайт проекту OpenBSD

Ось список засобів масової інформації, які використовуються для поширення інформації:

перший електронний лист під час встановлення сторінки посібника веб-сайт Веб-сайт Часті запитання Приклади Інформаційні бюлетені для оголошення

Давайте вивчимо їх один за іншим.

Після встановлення OpenBSD, коли ви вперше входите в систему як root, вас вітає повідомлення про те, що ви отримали електронний лист. Фактично, під час встановлення є електронний лист від Тео Де Раадта, який вітає вас із OpenBSD. Він дає вам кілька підказок щодо того, як розпочати роботу, але, що найважливіше, він спрямовує вас на сторінку довідки afterboot(8).

Сторінка довідки afterboot(8) описується як «речі, які слід перевірити після першого повного завантаження». Вона проведе вас через найпоширеніші зміни, які ви можете внести у свою систему. Найважливіше те, що тут пояснюється, як користуватися сторінкою довідки, наприклад перегляд розділу ДИВИТИСЯ ТАКОЖ, який веде до інших сторінок довідки, пов’язаних із поточною сторінкою.

Сторінка довідки afterboot(8)

§ Сторінки довідника

Сторінки довідки — це спосіб відправити документацію разом із програмним забезпеченням. Зазвичай ви знайдете сторінку довідки з такою самою назвою, як команда або файл конфігурації, який ви хочете задокументувати. Схоже, що сторінки довідок з'явилися в 1971 році, "man" означає посібник.

Сторінка Вікіпедії на сторінці посібника

Сторінки Man - це буквально серце документації OpenBSD, вони відповідають певним стандартам і містять багато метаданих. Коли ви пишете сторінку довідки, ви не лише пишете текст, але й описуєте свій текст. Наприклад, коли нам потрібно звернутися до іншої сторінки довідника, ми використаємо тег «перехресне посилання», цей розширений формат забезпечує точне відтворення, а також точний пошук.

Коли ми посилаємося на сторінку в текстовому чаті, ми часто пишемо її назву, включаючи розділ, наприклад man(1). Якщо ви бачите man(1), ви розумієте, що це довідкова сторінка для "man" у першому розділі. Існує 9 розділів довідкової сторінки, це старий спосіб сортування їх за категоріями, тому, якщо дві речі мають однакову назву, ви використовуєте розділ, щоб відрізнити їх. Ось приклад, «man passwd» виведе passwd(1), яка є програмою для зміни пароля користувача, однак ви можете прочитати passwd(5), який описує формат файлу /etc/passwd, у цьому якщо ви використовуєте "man 5 passwd". Я завжди вважав такий спосіб посилання на сторінки довідок дуже зручним.

У OpenBSD є сторінки посібника для всіх базових системних програм і конфігураційних файлів. Ми завжди намагаємося бути дуже послідовними у тому, як подається інформація, а формулювання ретельно вибираються, щоб бути максимально зрозумілими. Вони є спільними зусиллями за участю кількох рецензентів, зміни мають бути схвалені принаймні одним членом команди. Коли програму OpenBSD змінено, сторінку довідки слід оновити відповідно. Сторінки також час від часу оновлюються, щоб додати більше історії з поясненням походження команд, це завжди дуже інформативно.

Що стосується пакетів, немає жодної гарантії, оскільки ми включаємо лише початкове програмне забезпечення, вони можуть не надавати сторінку посібника. Однак розробники пакунків надають файл «pkg-readme» для пакунків, які потребують особливого налаштування. Ці файли можна знайти в /usr/local/share/doc/pkg-readmes/.

Онлайн-зчитувач сторінок OpenBSD Manual: багатий формат світить тут

Веб-сайт §

Один із способів розповсюдження інформації про OpenBSD — через веб-сайт, де пояснюється суть проекту, на якому апаратному забезпеченні його можна встановити, чому він існує та що він надає. Він містить багато корисної інформації до того, як ви встановите OpenBSD, тому його не можна знайти на сторінці довідки.

Веб-сайт OpenBSD

FAQ §

Я вирішив розглядати частину веб-сайту з поширеними запитаннями як інше середовище для документації. Це особливе місце, яке містить реальні випадки використання, які...