Як керувати документацією проекту з відкритим кодом? [зачинено]

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

• HTML-сайт
• A Github Wiki
• Файли розмітки, розміщені на Github
• Розміщення всіх документів у Github README.md

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

Я міг би використовувати бібліотеку Markdown для перекладу Markdown у HTML та відображення її на стильовому веб-сайті. Мені потрібно буде завантажувати зміни на веб-сайт у будь-який час, коли відбулися зміни, і було б важко керувати всіма різними "тегами" документації.

Вікіс Github (наскільки я знаю) не змінюється залежно від галузі, на якій ви перебуваєте. Отже, я міг мати лише "головну" версію документації у формі Github Wiki у будь-який момент.

Зробити це все в Github README - це якось акуратно. Я отримую розгалуження та тегування, але це трохи втомлює використання і не піддається легкій навігації.

Я пропускаю якесь дивовижне рішення? Які ще є варіанти?

Я б сказав, що документація ОБОВ'ЯЗКОВА бути у файлах вихідного коду (використовуючи будь-яку розмітку, яку ви хочете), а потім документи, згенеровані автоматично з них.
Принаймні на вашому веб-сайті ви можете генерувати форматовані завантаження документів як частина вихідного пакету, щоб користувачеві не потрібен певний інструмент для документа

Шанс когось іншого виправити / додати функцію, а потім відредагувати / додати трохи документації щодо розмітки, що знаходиться безпосередньо поруч із тим самим файлом, може бути низьким, АЛЕ шанс їх знайти зовсім інший файл у іншому сховищі документів, щоб зробити те саме, незначно менше нуля.

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

Якщо ваш проект є бібліотекою, нічого не перевершує документацію в стилі javadoc, щоб документувати синтаксис API з коментарів всередині самого коду.

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

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

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

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

Файли розмітки, розміщені з джерелом, працюють надзвичайно добре.

У РСТ на основі Docutils інструментів, наприклад, можуть створити HTML або латексний (і PDF - файли) з одного набору документів.

Це - фактично - поєднує ваш варіант 1 і варіант 3.

Якщо ви не проти перетворити документи з Markdown в reStructuredText, врахуйте Sphinx . Це так само просто, як і розмітка, але набагато потужніша.