Комментарии 3
А что за софт посоветуете для документации? Желательно с уклоном на REST API проекты.
А то как разработчику (ну нет у нас писателя) приходится делать и документацию (пусть и в кратком виде). Чаще это тупо md в репе с проектом, иногда wiki. Но хочется чего то более систематизированного или с шаблонами. А если есть возможность подменить еще и swagger то вообще замечательно.
Спасибо за вопрос! Как я понял, хочется инструмент, который автоматически из комментариев в коде соберет вашу документацию.
Из моего опыта, для доки C++ и Python использовали https://www.sphinx-doc.org/en/master/tutorial/automatic-doc-generation.html , а для JavaScript - https://jsdoc.app/ . Ну детали я рассказать не смогу, потому что установкой, настройки и тестированием занимались именно программисты. Технические писатели использовали только синтаксис.
Если говорить про РНКБ, то доку API (собранную автоматически) я видел только для мобильного приложения, и она создана на платформе https://swagger.io/ . По большей части мы работали с документами других типов, поэтому вернусь позже с ответом) Сейчас доку "уклоном на REST API" для своей интеграционной шины мы собираем вручную, но тоже с использование синтаксиса Swagger.
Про раздел "Поиск и навигация"
Про поиск
когда таким поиском можно пользоваться без отдельной инструкции к нему
Очень хочется пример, хотя бы один. Потому что
Если же для поиска нужны дополнительные телодвижения — значит, что-то с ним не в порядке
это про какого-то сферического коня. Не в порядке не с поиском, а с тем, что реализовать удобный человекомашинный интерфейс удалось пока только в фантастических фильмах. Поэтому - пример в студию, где сколь-либо расширенный поиск доступен к понимаю без инструкций
Про типа смешную картинку
Как бы выглядели настройки поиска, которым не хочется пользоваться
Не уверен. Совсем не уверен.
Такое динозавровое представление, как ни странно, порой гораздо удобнее многочисленных вложенных иерархий, окон. Тут надо про целеполагание интерфейса, а не сплеча "это плохо, а это хорошо всем и всегда".
Использование данной картинки как метафоры - неудачно
Хорошая документация: критерии, методика разработки и личный опыт техписателя