Ворочаем великими обсягами документації



  • А як ви підтримуєте довідку по API в актуальному стані?
  • Як можна організувати і зберігати локалізовані версії?
  • Ви перевіряєте текст на наявність неприпустимих символів і на валідність розмітки?
  • Як організувати перевірку (вичитку) топіків?


Ці та інші питання я часто чую від технічних письменників на конференціях. Для невеликих обсягів документації досить вручну переглянути документи і оновити/підставити/поправити все, що потрібно. А якщо обсяги документації виросли?

Наша документація зросла до більш ніж 154 000 документів тільки за .NET-лінійці продуктів, з них близько 140 000 документів — це довідка по API. Близько 8-10 тисяч топіків додаються кожен мажорний реліз (тобто двічі на рік). У цій статті я розповім як ми справляємося з такими обсягами.

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

Секрет успіху простий:


Зберігаємо так, щоб було зручно
Ми зберігаємо всі документи в MS SQL Server і зробили інтерфейс (CMS) для простого доступу до всіх документів та їх редагування, перевірки та перегляду.
Що ми отримали:
  1. Топіки — це запису в БД і ми до них навісили багато корисної службової інформації:
    • ім'я автора топіка і ім'я того, хто останнім цей топік правил.
    • дата створення, дата останнього редагування, історія редагувань.

    • різні статуси: перевірений чи коректором, схвалений чи розробником, потребує доопрацювання і т. д.
  2. Список топіків можна відобразити у вигляді таблиці з усіма її перевагами:
    • сортувати можна відсортувати документи в потрібному порядку, наприклад, за датою створення.
    • угруповання — можна групувати документи, наприклад, за статусом, по авторству, і т. д.


    • фільтрація — можна показати тільки ті топіки, які потребують уваги, відфільтрувавши всі інші
  3. Гнучкі можливості подання документів в БД. Ось деякі з найбільш смачних булочок:
    • Локалізація. В БД можна зручно організувати зберігання і доступ до локалізованої документації. Щоб контролювати процес локалізації, навісьте на топіки різні статуси: перекладено, не переведено, перевірено і т. д. Ми, правда, документацію не локалізуємо.

    • Структура API. В БД можна запросто організувати діаграму класів, ієрархію спадкування і т. д. Цю інформацію можна використовувати для генерації пов'язаних між собою документів.
  4. Технологія єдиного джерела. Якщо один і той же контент (зображення, приклад коду, текст) треба використовувати в декількох місцях, то цей контент можна зберігати як окрему сутність і посилатися на нього там, де він потрібен. З БД це робиться просто.



Автоматизируй це!
Автогенерація документів із зібраних бібліотек.
Є чудові інструменти, які дозволяють перетворити документаційні коментарі в коді в готові топіки. Це JSDoc, JavaDoc, Doxygen, Sandcastle, тисячі їх

У нас API описують технічні письменники в БД, а не розробники в коді. Тому нам не треба створювати готові топіки з коментарів в исходниках. Нам треба створювати порожні топіки в БД.

Цю задачу виконує спеціальний інструмент — синхронізатор. Працює він так:
  1. бере зібрані DLL-ки, через reflection витягує сигнатури всіх просторів імен, класів і т. д.
  2. звіряє сигнатури з тими, що є в БД.
  3. додає відсутню, видаляє зайве: наприклад, якщо в класі з'явився новий метод, то синхронізатор додає порожній топік для цього методу в БД з відповідними статусами.
Технічний письменник в інтерфейсі до БД відфільтровує всі топіки крім порожніх і описує свежедобавленные класи, методи, властивості і т. д.

Автоматичне заповнення контенту там, де це можливо.
Синхронізатор створює порожній топік для нового елемента API, і заповнює всю супутню інформацію. Візьмемо, приміром, ось цей документ: ASPxGridView.StartRowEditing Event.

Жовтим маркером я виділив інформацію, яку заповнює техписатель безпосередньо для цього топіка. Особливо виділив розділ з прикладом коду (помаранчевим): на нього треба дати посилання у відповідному полі. Весь вміст прикладу належним чином затягнеться в документ.



Решта ж генерується автоматично:
  1. Простір імен поточного класу і бібліотека, в якій цей клас лежить, ставляться автоматом.
  2. Синтаксис оголошення на C# і VB.NET складається автоматично на підставі службової інформації.
  3. Додаткова інформація про подію так само витягується автоматично.
  4. Крім того, автоматично підставляється табличка з публічними властивостями класу, який містить дані події (event args).
  5. Як я писав вище, на приклад досить дати посилання, все вміст прикладу підтягнеться сама. До речі, на цей же приклад можна послатися з іншого топіка.
  6. Посилання на відповідний клас, члени класу і простір імен генеруються автоматично. Техписатель може додати ще кілька посилань на свій розсуд.
Деякі топіки, наприклад ті, що містять список членів класу, генеруються повністю автоматично. Ось список членів класу ASPxGridView. Уявляєте яке було б підтримувати цей список вручну?


Тестування, безперервна інтеграція і code review
Ми пишемо документи XML-подібному форматі. По суті, документація — це теж свого роду код. В ньому можна помилитися: не закрити тег, ввести неприпустимі символи і т. д.

Користувачі отримують документацію в більш человекочитаемых форматах (HTML на сайті, CHM, PDF, MSH), тобто документацію необхідно зібрати з исходников. Виправляти помилки, накопичені за весь період до підготовки релізу — довго й дорого, тож документація повинна завжди бути собираема і оттестирована.

Ми вчинили логічним чином.

  1. Написали тести до документації. А чому б і ні? Можна автоматично перевіряти синтаксис в заголовках топіків, можна перевіряти биті посилання, закритість всіх тегів, наявність поганих слів у тексті або не-ASCII символів (російську «З» замість латинської «C»). Тести ганяються на CI сервері.
  2. На сервері CI так само щодня збирається білд з інсталяцією документації. Якщо раптом не збирається, то ми дивимося білд-лог, вживаємо заходів і запускаємо перезбирання.
  3. Code reviewСontent review, простіше кажучи, вичитка та перевірка. Перевірка є граматична і фактологічна.
    • Граматична. Документацію ми пишемо на англійській мові, а так як ми, техписатели, не носії англійської, то наш текст на граматику перевіряють коректори, у яких англійська мова — це рідна мова. Коректори перевіряють документи у тій же CMS, в якій техписатели створюють документацію.
    • Фактологічна. В CMS передбачена можливість попереднього перегляду топіка у вигляді HTML-сторінки (точно такий же як на сайті). Посилання на цю сторінку можна надіслати розробнику, щоб той міг прочитати документ і запропонувати поліпшення.
Висновок
У коментарях до хабратопику з радістю відповім на ваші запитання. Буду радий похоливарить обговорити різні організаційні і технічні моменти, що стосуються написання документації, взаємодії з розробниками і користувачами.
Джерело: Хабрахабр

0 коментарів

Тільки зареєстровані та авторизовані користувачі можуть залишати коментарі.