Я заплатил людям, чтобы они попробовали пройти мой README
I paid people to try and follow my README
Разработчики плохо пишут документацию, и мы часто говорим RTFM, хотя читать нечего. Автор заплатил незнакомцам по €25 за час, чтобы они вслух проходили установку ActivityBot по README. Он записывал их замешательство и после каждой сессии правил текст. Среди находок: неверная ссылка на демо, непонятные команды, запутанный порядок разделов и шутки, которые только сбивают с толку.
В общей сложности я заплатил около €150, чтобы куча людей критиковала меня в лицо. Эй, дешевле, чем терапия, правда?
- bambax
> Но свои собственные предубеждения игнорировать очень трудно. Конечно, ты знаешь, что для некоторых команд нужен sudo, и очевидно, что когда ты написал -foo, ты имел в виду --foo, и все знают, что после этого надо перезагрузиться.
Иногда я пишу readme для себя, чтобы помнить точные шаги для генерации отчёта по данным и т.п.
Удивительно, насколько они становятся непостижимыми уже через пару недель; когда всё в голове, всё ясно, плавно и само собой разумеется; но как только мы забыли контекст, ничего больше не имеет смысла.
- piro0919
Я согласен наполовину.
Я собираю приложения с помощью Claude Code и тестирую их, заставляя ИИ кликать по интерфейсу через Playwright. Этого достаточно, чтобы проверить, что всё работает как задумано и ничего не сломано.
Но я думаю, что цель разная, когда пробует ИИ и когда пробует человек. Если выразиться радикально, ИИ — для UI, а люди — для UX. Хотя люди тоже находят проблемы UI: в моём музыкальном плеере песни перестали воспроизводиться в Safari на настоящем iPad, и я обнаружил это только когда сам им воспользовался. То, что нашли в этой статье, — например, шутки, которые не зашли, или непонимание, что вообще делает инструмент, — относится к той стороне, которую могут найти только люди.
(Я написал это по-японски и перевёл с помощью ИИ.)
- andai
>Я вообще-то не объяснил, что будет делать программа.
Половина постов, которые я вижу в последнее время, выглядят так: «Gleam 2.0. Чему мы научились», а потом заходишь на главную страницу, а там «Gleam — это Tribble для твоего Fork! (Прокрутите вниз) Проверьте, подходите ли вы для Gleam Enterprise!»
- bryanhogan
Это очень близко к тому, что в области UX-дизайна называют юзабилити-тестированием.
У Nielsen Norman Group есть хорошее введение в это: https://www.nngroup.com/articles/usability-testing-101/
Интересно ли это людям на HN?
Я учился по специальности на стыке программирования и дизайна.
- extralongdivisi
> Я вообще-то не объяснил, что будет делать программа.
Не могу сосчитать, сколько README я прочитал, построенных по шаблону: «<неинформативное-название> — это <модное слово> <модное слово>, написанный на <языке>». Я получаю лишь смутное представление о том, что оно делает, только после использования или просмотра демо; слишком часто демо недоступно через README.
- legacynl
Обожаю это. Большинство readme просто ужасны. Самое вопиющее, я считаю, — когда в readme не сказано, что делает проект. Понимаю, что не каждый проект рассчитан на публику, но если уж ты взял на себя труд создать файл readme, почему бы не пройти лишние 10 сантиметров и не написать самую базовую информацию?
Другие проблемы:
* устаревшая (а значит, неверная) информация
* использование сокращений без расшифровки (бонусные очки за сокращения, у которых есть общеупотребительные значения, например: EG, NB, IE, ETC)
- trollbridge
Это одна из тех вещей, в которых LLM действительно хороши.
Создай новый контейнер или песочницу, скопируй туда git-репозиторий или укажи на свою staging-документацию и посмотри, что получится.
- tilemarch
Люди — это здорово, но ИИ здесь тоже может реально помочь. Позвольте объяснить :)
Я пишу документацию, которой должны следовать ИИ-агенты, чтобы пройти игру через API, затем запускаю 20 субагентов, у каждого своя личность / свойства и т.д., и смотрю, где они спотыкаются. Они застревают в тех же местах, что и люди..
или указывают на «очевидные» шаги, явно не упомянутые.
А вот где ИИ-тесты начинают разваливаться: агент не говорит тебе, что документация запутанная, он просто делает что-то не так с полной уверенностью. Человек на созвоне говорит «погоди, что?» — и это стоит 25 евро :)