Есть хорошая топология документации: tutorials, guides, explanations, reference. Я писал про нее три года назад и с тех пор активно использую в работе. Всё это время я видел в ней только логику пользовательского пути:

1. Разработчик пишет hello world, чтобы попробовать и заинтересоваться.
2. Проходит несколько гайдов, чтобы опробовать технологию в деле или разобраться, как решать конкретную задачу.
3. Потом читает объяснительные статьи и разбирается в тонкостях технологии. Это путь к профессиональному владению инструментами.
4. Наконец, после пары лет уверенного пользования инструментом, разработчик только заглядывает в референс, когда не помнит деталей API.

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

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

2. Гайды по решению конкретных задач нужны для того, чтобы ускорить разработку до состояния прототипа, proof of concept. На основании этого прототипа бизнес будет решать, вкладывать ли дальше ресурсы в разработку решения на вашей технологии, или выбрать что-то другое. А еще набор типичных решаемых задач помогает предпринимателям находить такие задачи в окружающем мире и решать их именно с помощью вашей технологии.

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

4. Наконец, подробный референс становится наиболее важен на этапе стабильного развития продукта, когда есть десяток разработчиков и роадмап на год вперед. На этом этапе у продукта уже есть накопленная кодовая база, которую нужно поддерживать и развивать. Поэтому важно, чтобы API менялся не слишком часто, только в лучшую сторону, и все эти изменения были задокументированы.

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

Желаю вашим продуктам дожить до этого прекрасного времени. :)