Ако отговорите с НЕна въпросите по-долу, тогава може би тази публикация и други от поредицата ще ви помогнат да пишете и управлявате по-добра документация 📝.

  1. ДОВЕРЯВАТЕ ли се на настоящата си документация?
  2. Съществува ли само един източник на истина за вашата документация?
  3. Лесно ли се намира?
  4. Лесно ли е да се изгради графиката на зависимостта от текущата документация?
  5. Винаги ли е в синхрон с функциите на вашата кодова база?
  6. Лесно ли е да разберете регистрационните файлове за промяна или освобождаване?

Много е важно да поддържате документацията на вашия код, тъй като това помага на другия разработчик да разбере архитектурата на вашия код, архитектура, проект и инфра.

Писането на документация може да забави вашата индивидуална скорост, но с добра документация целият екип или организация ще работи светкавично бързо ⚡.

Какво представляват Doc Smells? (Термин, вдъхновен от кодови миризми)

  1. Писането на документацията като отделна задача и най-вече чрез разглеждане на кода, опитвайки се да извлечете документацията.
  2. Създаване на множество копия на една и съща документация на различни места. Тъй като е трудно да се поддържат всички тези копия с малки промени.
  3. Писане на документация, фокусирана само върху една група.
  4. Писане на документация на следните места:
    4.a. Билети
    4.b. Споделени папки
    4.c. Sharepoints или One note
    4.d. Onedrive
  5. Използване на грешни тагове и етикети към документа.
  6. Само разработчик или мениджър допринася за документацията.

Трябва ли всичко да се документира?

  1. Да, би било добра идея първоначално да го документирате и след това да го обобщите, което трябва да бъде на разположение за дълго време.
  2. Ако включва множество заинтересовани страни, то трябва да бъде документирано.
  3. Критичната информация, която помага при вземането на решения, трябва да бъде документирана.

Дизайнът трябва да отразява тяхното значение и да следва еднаквост и стандарти

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

По същия начин документацията трябва да е на същите принципи, които могат лесно да се възприемат от човешкия мозък. Например критичната информация трябва да е в червено, а предупрежденията трябва да са в жълт цвят. Добавянето на цветове, диаграми, символи помага информацията да се следва и разбира по-лесно.

Какво и как документация

Какво — Тя е по-ориентирана към обяснението какво прави продуктът. И информацията е налична в README.md , wiki , docs или уебсайт на външен продукт.

Пример: https://gofeatureflag.org/docs

Как — Писането на CLI програма и обяснението на описанието на флага е вътрешната документация, която е вградена в кода.

Пример: https://github.com/thomaspoignant/go-feature-flag/blob/main/config.go#L14

Точност на документацията

  1. Създаден от един източник на истина.
  2. Контролирана версия.
  3. Трябва да се прегледа.
  4. Неуспешен тестов код с промяна в документацията.
  5. Няма излишна информация.
  6. Отхвърлената информация трябва да бъде изтрита с увереност.
  7. Дайте му време и го напишете изцяло. Не пишете непълна информация и не оставяйте запазените места.

Писането на тестове, документирането на код, създаването на диаграми не се считат за забавна дейност. Сега ни остават 2 опции, или да ги направим като забавна дейност, или да я автоматизираме.

Правенето на документация като забавно занимание

  1. Добавете карма точки, тъй като документирането на кода не е част от работата, но е решаващо нещо. Наградите ни правят щастливи, вижте групата във Facebook, с етикетите до вашето име Top Contributor ви кара да се мотивирате повече да допринасяте повече за групата.
  2. Преследване на вътрешните форуми и чатове, за да намерите правилната информация.
  3. И още идеи ще бъдат обсъдени в предстоящата публикация от тази серия

Автоматизиране на документацията

  1. С помощта на CI/CD инструменти актуализирайте документацията си.
  2. И как да се постигне това ще бъде обсъдено подробно в следващите публикации.

Любопитно е да разберете как документацията може да се провали на вашите тестове. Разгледайте една от съществуващите ми публикации за развитие, управлявано от поведение:



Нов съм в разработката, управлявана от поведение, използвайки Go
Бизнесът и ИТ невинаги се разбират. Изпълнимите спецификации на Godog насърчават по-тясното сътрудничество...levelup.gitconnected.com



Статии от поредицата:

  1. „Разбиране на проблема“

Мога ли да ви помоля любезно да пляскате 👏 и да споделите ✈ към публикацията, ако ви харесва. ❤