Розробники Чому ви не повинні пропускати документацію

У сфері розвитку мобільних додатків, веб-додатків, настільних додатків або бібліотек JavaScript документація відіграє важливу роль, яка може визначити успіх розробки програмного забезпечення. Але якщо ви коли-небудь робили документацію, ви б погодилися зі мною, що це найменш улюблені речі для розробників.

На відміну від написання коду (це те, що зробили розробники), документація (яку ми не зробили) має і повинна бути легко засвоєна кожен. Технічно ми повинні перекласти машинну мову (код) на мову, зрозумілу для людей, що є більш жорстким, ніж здається.

Незважаючи на те, що це може бути справжнім обтяжливим завданням, написання документації є важливим і дасть переваги для ваших користувачів, ваших колег і, особливо, самого себе.

Хороша документація допомагає користувачам

Документація допомагає читачеві зрозуміти, як працює код, очевидно. Але багато розробників роблять помилку, вважаючи, що користувачі програмного забезпечення будуть досвідченими. Отже, документація може бути тонким матеріалом, пропускаючи багато основних предметів, які вона повинна містити з самого початку. Якщо ви розумієте мову, ви можете зрозуміти справу за вашою власною ініціативою; якщо ви не є, то ви втрачені.

Документація, призначена для користувачів, зазвичай складається з практичного використання або “як”. Це правило полягає у створенні документації для загальних користувачів воно має бути чітким. Використання сприятливих для людини слів краще, ніж технічні терміни або жаргон. Приклади реального використання також будуть високо оцінені.

Хороший дизайн макета також дійсно допоможе користувачам просканувати кожен розділ документації без напруги. Кілька хороших прикладів (моїх улюблених) - це документація для Bootstrap та WordPress “Перші кроки з WordPress”.

Це також допомагає іншим розробникам

Кожен розробник матиме власний стиль кодування. Але, коли справа доходить до роботи в команді, нам часто доводиться ділитися кодами з іншими товаришами по команді. Тому дуже важливо мати консенсус щодо стандарту щоб зберегти всіх на одній сторінці. Належним чином написана документація була б еталоном, який потребує команда

Але на відміну від документації кінцевого користувача, ця документація зазвичай описується технічні процедури подібно до назв кодів, що показує, як конкретні сторінки повинні бути побудовані, і як API працює разом з прикладами коду. Часто ми повинні писати документацію вбудовано з кодом (відомий як коментарі), щоб описати, що робить код.

Крім того, у випадку, коли у вас є приєднання нових членів ваша команда пізніше, ця документація може бути ефективним часом для навчання їх, так що вам не доведеться надавати їм 1-на-1 запуск коду.

Дивно це також допомагає кодеру

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

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

Документуючи ваші коди, ви зможете швидко і без розчарування дістатися до нижньої частини коду, заощаджуючи багато часу, який можна витратити на отримання змін.

Що робить для доброї документації?

Існує кілька факторів, які допоможуть побудувати добру документацію.

1. Ніколи не припускайте

Не вважайте, що ваші користувачі знають, що ти знати як і що Вони хочу знати. Це завжди краще починати з самого початку незалежно від рівня знань користувачів.

Наприклад, якщо ви створили плагін jQuery, ви можете взяти натхнення з документації SlickJS. Він показує, як структурувати HTML, куди помістити CSS і JavaScript, як ініціалізувати плагін jQuery на самому базовому рівні, і навіть показує повну кінцеву розмітку після додавання всіх цих елементів, що є чимось очевидним..

Суть у тому, що документація написана з думкою про користувача, а не про розробника. Наближення вашої власної документації таким чином дасть вам кращу перспективу в організації власного твору.

2. Дотримуйтесь стандарту

Додавання документації, що йде вбудовано з кодом, використовувати стандарт, який очікується від мови. Це завжди гарна ідея для опису кожної функції, змінних, а також значення, що повертається функцією. Ось приклад гарної вбудованої документації для PHP.

 / ** * Додає користувацькі класи до масиву класів тіла. * * @param array $ class Класи для елемента body. * @return array * / function body_classes ($ classes) // Додає клас блогу в блогах з більш ніж 1 автором. if (is_multi_author ()) $ classes [] = 'груповий блог';  повернення $ класів;  add_filter ('body_class', 'body_classes'); 

Нижче наведено кілька посилань на форматування вбудованої документації з найкращими практиками в PHP, JavaScript і CSS:

• PHP: PHP Документація Стандарт для WordPress
• JavaScript: UseJSDoc
• CSS: CSSDoc

Якщо ви використовуєте SublimeText, я б запропонував вам встановити DocBlockr, який буде вправно заповнювати ваш код вбудованою документацією.

3. Графічні елементи

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

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

4. Розділення

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

Додайте вміст і розділіть документацію в легкозасвоюваних розділах, але зберігайте кожну секцію доречною з наступним. Тримайте його коротким і прямим. Нижче наведено приклад добре організованої документації в Facebook. Зміст переводить нас до місця, де ми хочемо перейти в клік.

5. Переглянути та оновити

Нарешті, перегляньте документацію на наявність помилок та перегляньте її, якщо це необхідно або коли і є істотні зміни у продукті, програмному забезпеченні або бібліотеці. Ваша документація не буде корисна для будь-кого, якщо вона регулярно не оновлюється поряд з вашим продуктом.