Цільова аудиторія
Я думаю, відповідаючи на це питання, вам справді потрібно запитати, хто має на увазі прочитати цю документацію. Користувач або навіть бізнес-аналітик розробник має грубо різні потреби.
- Як розробник: документація, пов'язана з кодом, який вивчається, деталі, такі як контракт на інтерфейс, та приклади використання. Можливо, якась документація на високому рівні та специфікація протоколу на добру міру.
- Як Користувач: документація, доступна через меню довідки, або на доступному веб-сайті про використання програмного забезпечення.
- Як бізнес-аналітик: корисна документація, доступна як документи, або як доступний веб-сайт. Найкраща інформація про протоколи, архітектуру високого рівня та випадки використання є найкращими.
Технічне обслуговування
Про те, де розмістити джерело цієї документації, буде залежати від вашої аудиторії та хто пише для вашої аудиторії.
- Є лише будинок забудовників? Помістіть усе в коді. Це спонукає його до оновлення. Вам потрібно буде працювати над культурою, яка заохочує оновлення документації бути такою ж важливою, як і зміни коду.
- Є будинок розробників та письменників документації? Розподіліть обов'язки. Використовуйте для розробників інструменти, орієнтовані на розробників, використовуйте інструменти для створення документації для розробників.
По можливості переконайтеся, що можуть бути виконані приклади коду чи випадки використання. Автоматизуйте їх виконання та внутрішньо відмовте прапор. Можливо, ці сторінки є поганою або поганою документацією.
Крім того, якими б інструментами ви не хотіли писати свою документацію, вам потрібні надійні засоби пов’язати конкретну версію документації з конкретною версією коду. Це все ще вигідно навіть у щасливій хмарній землі з єдиним вічнозеленим розгортанням.
Інтегрування документації
Інтеграція може знадобитися для створення певної документації, але зауважте, що лише користувач очікує, що єдине місце отримає доступ до всієї необхідної документації.
Бізнес-аналітик цілком задоволений специфікаціями API, розробленими специфікаціями та сценаріями використання, які розміщуються в окремих документах або в окремих розділах веб-сайту.
Розробник надає перевагу всьому, що видно з джерела, але дуже радий мати пару високоякісних дизайнерських документів та детальні документи із специфікацією протоколу, що знаходяться поза кодом, хоча бажано в межах одного замовлення.
Ваша справа
Якщо чесно, документація у вашій вікі, мабуть, не є такою ж документацією у вашій кодовій базі. Злиття теж може не мати сенсу.
З іншого боку, інтегрування цих двох можна дозволити кількома простими способами.
- Інструменти джерельної документації (як doxygen) можуть створювати html, а вікі живе на веб-сервері. Це було б простою точкою інтеграції - просто обслуговувати вбудовану версію поряд із вікі та з'єднувати їх між собою.
- Деякі продукти wiki дозволять вам запускати вікі безпосередньо з файлу, який ви можете зареєструвати в кодовій базі. Це дає простий інструмент wysiwyg, зберігаючи документацію в парі з кодом.
- Також можуть бути розміщені інші формати, такі як pdf, але це зводиться до конкретних інструментів, які ви хочете використовувати. Можливо, має сенс скребти свою вікі у файли розмітки та подавати її через doxygen (або інші інструменти). Можливо, має сенс pdf-файл wiki та джерела окремо та використовувати інструмент злиття pdf.
Наприкінці дня з’ясуйте, яка система документації має низькі витрати на обслуговування, і допоможе вам у постачанні високоякісного продукту, як це бачать аудиторія розробників, бізнес-аналітиків та користувачів. Все, що заважає будь-якій із цих груп, обов'язково знизить якість продукції.