Documentation features

[BANOnotIT]

So far documentation of the project was kinda State of the Art mainly because of custom look and feel and information structure leaning towards describing internal structure. Such approach makes things interesting to create but on other hand creates friction for new comers.

Right now many documentations lean towards tutorial based documentation with reference. Main examples are https://docs.nestjs.com and https://nextjs.org/docs which presents all documentation as a series of tutorials "from simple to advanced". Also react team made a great refactor of their documentation on https://react.dev and introduced two workflows: "Learn" containing tutorials and system design decision explanations and "Reference" containing mainly definitions and simple usage examples.

All these examples are content-rich and require much effort to achieve same result. Thus I propose following things that can be done one by one to go towards good practices:

• Create a separate landing page to Sell the project to newbies
• Separate current documentation in main 3 sections: Reference, Tutorials, Blog
• Use generalized documentation layout containing:
  • Table of Contents of current page
  • Simple enough mobile version
  • Global navigation
• Make "Getting started with React" tutorial to integrate people without needing to communicate in russian speaking chat
• Integrate site global search (might be algola for starting but can be something self-hosted and reatom-based for dog-fooding)
• Move old v1 documentation to v1.reatom.dev and create CNAME redirect to that domain (like react did)

There are also nice to have features that might be done to improve UX but are not required:

• TypeScript/JavaScript switchers
• Dark/Light theme
• Offline-first variant and/or integration with https://devdocs.io

P.S. Отвечать можете на русском, главное мысли здесь, а не в чате.

[dimatakoy]

Привет!

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

Я бы ориентировался на документацию vuejs. У неё более плоская структура туториалов и есть классный отдельный раздел API, в котором уже более низкоуровнево описывается каждый метод. Думаю эту доку можно генерировать с помощью jsdoc.

Особенно в доке vuejs мне нравится раздел https://vuejs.org/guide/essentials/reactivity-fundamentals.html#declaring-reactive-state, в котором очень простым языком рассказывается про реактивные примитивы vue. Здесь же хочется напомнить, что половина популярности vuejs пришла за счет простой документации, которые очень легко понимали новички.

Дока nestjs отличная, но она написана для людей, которые уже почитали Мартина Фаулера и понимают как строить что-то большое на примитивах, которые даёт нест.

---

Гайд как писать читаемые тексты тоже может быть полезен:
https://readabilityguidelines.co.uk/

[BANOnotIT]

I agree that nestjs' documentation is kinda full blown but so is nestjs! Yet reatom tries to be simple and composable and "the canonical way" tutorial wouldn't work as it does for nestjs.

I also agree that vuejs is really "flat" and it's definitely easier to skim through to find the article that suits your case. But I don't think reatom has settled best practices and workflows that can be presented in documentation. And I wanted to start that settling process by creating getting started tutorials that'll force us to prepare content and methodology. These discussions and tutorials should lead us to some common workflow that we can sell to others.

Thanks for mentioning jsdoc! I was thinking of its superset tsdoc but just forget to mention it.

Thanks for the readability guidelines. Will take a more precise look tomorrow!

[BANOnotIT]

@dimatakoy mentioned https://docs.divio.com/documentation-system/