Пользовательская документация и GitHub

[DevMan]

имхо, намного удобнее связка в виде доксетов + вьюер для них (dash, velocity, zeal).

[stas404]

Говорят, если приложить документацию к уху, то можно услышать шум моря.

[SirEdvin]

Я считаю странным, что исходный код не распространяется с пользовательской документацией.

Почему?
Причина мне кажется весьма очевидной.
Исходный код уже написан, а составление для него документации — это отдельная задача.
Причем чем больше проект, тем нужно больше времени на это убить.

[Delphinum]

Те же аргументы можно привести относительно тестов. Код и без них может прекасно работать и на их составление прибется убить уйму времени, но их хранят вместе с исходниками.

[SirEdvin]

Я видел так же много кода без тестов.
Например, в официальном репозитории calibre, я не нашел тестов (может плохо искал).
Но тесты часто нужны самим разработчикам и пишутся ими во время разработки.
А пользовательскую документацию нужно писать отдельно в любом случае.

[Delphinum]

Но тесты часто нужны самим разработчикам и пишутся ими во время разработки

Если вы пишете OpenSource сугубо для себя, то да, можно (возможно) обойтись без документации.

А пользовательскую документацию нужно писать отдельно в любом случае

Что же мешает делать это параллельно с написанием кода? Программирование через Readme сильно упрощает разработку.

[SirEdvin]

Если вы пишете OpenSource сугубо для себя, то да, можно (возможно) обойтись без документации.

Мне кажется, не возможно, а почти наверняка она будет без документации.

Что же мешает делать это параллельно с написанием кода? Программирование через Readme сильно упрощает разработку.

Если я не ошибаюсь, это две разные задачи.

[Delphinum]

Мне кажется, не возможно, а почти наверняка она будет без документации

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

Если я не ошибаюсь, это две разные задачи

Ну так и тестирование это другая задача, но параллельное их выполнение положительно сказывается и на обоих процессах.

[SirEdvin]

Ну так и тестирование это другая задача, но параллельное их выполнение положительно сказывается и на обоих процессах.

То есть, когда вы пишите код, вы не запускаете его потом, что бы проверить, сработает ли оно?

[Delphinum]

Код можно и запустить, но автоматические тесты для этого писать не обязательно.

[khim]

Разница между пользовательской документацией и тестами совсем в другом. Тесты (какие бы они ни были) помогают прежде всего разработчику, который «в теме». Пользовательская документация нужна там, кто ещё не въехал.

Хотя на самом деле писать пользовательскую документацию, конечно, нужно. И именно разработчику. Просто потому, что когда вы попытаетесь подробно описать «как этим пользоваться» и увидите весь тот ужас, который у вас выльется на бумагу, то вы пойдёте и причишите наконец хидеры и прочие интерфейсные файлы! А то и API подправите… А профессиональный документописатель этого сделать, конечно, не сможет.

Но вот уже полноценные мануалы и «поучительные истории» — тут да, тут, наверное, смешивать с разработкой не стоит.

[Delphinum]

Но вот уже полноценные мануалы и «поучительные истории» — тут да, тут, наверное, смешивать с разработкой не стоит

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

[aikixd]

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

[SirEdvin]

Одним из главных недостатков Open Source является то, что слово должны тут не очень работает.

[aikixd]

Это свободный рынок, открытый код — это такой же товар. Если он плохого качества то не ждите репортов и коммитов.

[SirEdvin]

Зависит от того, зачем этот код.
Например, моды для minecraft часто без документации (readme файл не в счет, там просто описание).
Документация к инструменту для написания модов (Forge) плоховата, на самом официальном сайте полно устаревшей информации, про официальную вики страшно говорит, но…
Приходится с ним работать.

[AlexXYZ]

Я вас полностью поддерживаю, не смотря на очевидность. Лучше лишний раз напомнить разработчикам, что нужно писать пользовательскую документацию. Хотя разработчик думает, что «и так всё понятно» (много кода или мало), но даже он, переключившись на другой проект и через неделю вернувшись обратно уже сам будет плавать в своём коде и чесать лоб, зачем что-то было сделано? Меня уже не раз выручали такого рода документы, которые я сам же себе и писал. Ещё если бы и не лень было делать скриншоты, чтобы знать, что должно получиться в итоге.

Было бы правильно, если бы вы кроме обозначения проблемы вы провели бы анализ, откуда вообще берётся «нежелание» писать документацию? Я возьму на себя смелость заявить, что действительно трудно просто писать документацию, т.к. нет хороших инструментов для этого. На каждое простое действие (например, сделать скриншот и вставить его в справку) — целая задача, отвлекающая от написания документации — собственно, сделать скриншот, «обтравить» его стрелочками и надписями, «сохранить» в каталог, а потом ещё и в тексте (если это markdown) дать ссылку. Т.е. после таких мыслей садиться и писать документацию совсем не хочется. Если у вас есть какой-то набор инструментов, который позволяет вам упростить эту задачу, не могли бы вы поделиться им и рассказать нам бонусы от их применения? У меня например zim desktop wiki (для заметок), ditto (clipboard manager), fast stone capture (пачками плодить скриншоты и накапливать их в ditto, потом пачкой вставлять в zim). Но это мой личный набор.

[Delphinum]

Отсутствие удобных инструментов это одна из проблем. Другой является неумение писать документацию. Часто разработчик относится к написанию документации как к написанию книги, старается подобрать слова, украсить их элементами могучего Русского языка и сделать красивое оформление, что превращает его в писателя.

[AlexXYZ]

Конечно. Но ведь и программистом человек становится не сразу. Много пробует, ошибается в итоге обретает чувство баланса и начинает писать код вполне нормально. Так и с документацией. Написал для себя, прочитал через неделю, заметил огрехи, поправил. Потом уже пишешь без этих огрехов. В написании документации есть большой плюс — начинаешь думать уже как пользователь и лучше понимаешь что и зачем есть в программе.
Исключительно из любопытства, если касаться технической стороны написания документации, не могли бы вы поделиться какими-то программками или удобными (на ваш взгляд) ресурсами, которые могут упростить написание документации?

[iroln]

В мире Python пользовательскую документацию обычно всегда пишут с использованием Sphinx, хранят в репозитории вместе с исходными кодами и автоматически хостят на ReadTheDocs. И всем хорошо. :)

[lair]

Во-первых, на гитхабе есть GitHub Pages, которые предназначены ровно для того, о чем вы пишете, но при этом позволяют не смешивать код и обобщенную документацию.
Во-вторых, для многих языков есть встроенные средства документирования, которые позволяют генерить необходимую информацию на основании разметки прямо в коде.

[Delphinum]

Во-первых, на гитхабе есть GitHub Pages, которые предназначены ровно для того, о чем вы пишете

Когда я пишу небольшой проект, мне удобнее хранить и редактировать документацию параллельно с кодом проекта, а не переключаться на GHP. GHP это отличное решение, но, на мой взгляд, больше подходит для довольно крупных проектов, автору которых не лень рекламировать свой продукт.

Во-вторых, для многих языков есть встроенные средства документирования, которые позволяют генерить необходимую информацию на основании разметки прямо в коде

Я об этом упоминал в статье. Это документация API, а не пользовательская документация. В статье обсуждается второй тип документации.

[vaniaPooh]

Кстати, вики на Гитхабе — это тоже отдельный git-репозиторий, который можно отдельно версионировать.

[Delphinum]

Да, тоже хорошее решение. Проблема только в том, что это число GitHub'овское решение, и если ваш пользователь потеряет доступ к GH, то ему документация станет не доступна. Это может показаться глупым, интернет сегодня стабильный, а GH обещал долго жить, но когда начинаешь мотаться по командировкам в места без цивилизации, понимаешь что все должно быть на готове.

[Delphinum]

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

[Delphinum]

читаешь доки на сайте CPAN

А если нет доступа к CPAN?

[Delphinum]

Доки в исходниках я люблю, но мне кажется их должно быть:
1. Немного
2. По существу
Считаю пользовательскую документацию лучше выносить. Так ее будет проще править и переводить силами самих пользователей.

[Xao]

Но ведь есть github wiki для каждого репозитория, более того, их можно клонировать себе, и вести как отдельный репозитрий, для удобства.

[khim]

Самая большая проблема любой документации — её актуальность. Любой другой репозиторий, кроме основного — это проблема синхронизации.

Потому вне репозитория должна жить только та документация, актуальность которой не будет поддерживаться. Скажем обзорные статьи, где ссылки на конкретные API — это только примеры. А всё остальное — должно быть в основном репозитории.

[zahardzhan]

Мне кажется в вашем примере с роутингом отдельная документация в формате маркдаун это оверкил. Javadoc-образных средств документирования и грамотного ООП-дизайна для подобных программ хватает с головой (с учетом того что они будут разрабатываться и использоваться в основном как библиотеки из специализированных IDE).

Я сейчас тоже экспериментирую с документацией, только там подход немного другой. Весь проект состоит из одного единственного README-файла документации, и программа на языке высокого уровня генерируется непосредственно из README-файла с помощью IDE, то есть отдельных исходников как таковых вообще нет.

[Delphinum]

Мне кажется в вашем примере с роутингом отдельная документация в формате маркдаун это оверкил

Отчасти соглашусь. У меня есть пакет с 1 файлом и 2 файлами документации ) Часто можно обойтись DocBlock-комментами в стиле Javadoc.

Весь проект состоит из одного единственного README-файла документации, и программа на языке высокого уровня генерируется непосредственно из README-файла с помощью IDE

IDE дали искуственный интеллект? )

[zahardzhan]

Эта IDE была разработана в Лаборатории Искусственного Интеллекта MIT, так что да ) Вот черновик, можете глянуть, но смотрите быстрее пока я не закрыл доступ gitlab.com/zahardzhan/well-tuned-emacs

[Delphinum]

я там не зареган, потому — спасибо, нет )

[zahardzhan]

Вообще, если интересуетесь документацией ИТ-проектов, посмотрите на TeX, потому что он эпически документирован во всех отношениях www.dropbox.com/s/868kii13wtifswx/tex.pdf?dl=0 www.dropbox.com/s/ov098y98q8wcyum/tex.web?dl=0 www.dropbox.com/s/mw24dccitb8nee2/TeXbook.pdf?dl=0

[Delphinum]

Благодарю.

[nick_volynkin]

Кстати, ваши ссылки в markdown можно упростить. Вместо

[composer.json][]

[composer.json]: ./composer.json

Достаточно

[composer.json]

[composer.json]: ./composer.json

[Delphinum]

Буду знать, спасибо.

[AlexanderS]

Документация это хорошо. Но минусом является наличие браузера и «живого» интернета для доступа ко всем этим wiki и git docs. А конвертация в автономный текст не предполагается движками изначально. На память пожалуй только Nextcloud приходит, так как там ребята интерактивные доки конвертят в pdf, который можно скачать и автономно почитать если что.