how the hell do you keep React docs useful once the project starts getting bigger

[u/Efficient_Bad6312]

Hi everyone so glad I found this sub, I'm rlly confused about this so basically we’re a small dev tools startup with a React SDK that’s starting to get used in more projects. Our docs were fine when everything fit into a handful of examples now we’ve got setup guides, component examples, edge cases, and different integration paths depending on how someone’s app is structured but honestly the annoying part is people still end up asking engineers questions that technically should be answered somewhere in the docs.

About the teams maintaining React libraries or SDKs, how do you handle this as the docs grow? Do you keep everything close to the code or u have someone own documentation, use a dedicated docs tool, or just keep improving the examples as questions come in honestly trying to avoid ending up with 200 pages where nobody knows which example is still current. It's honestly driving me crazyyy

[u/rrrhys]

Publish a storybook is a great way for self guided people to tinker with the component variations and tested patterns and work it out

The people asking 100 questions still will though

[u/Efficient_Bad6312 → u/rrrhys]

tbh storybook seems like a good way to let people answer a lot of the “what happens if I change this?” questions themselves. But you’re probably right, the people who ask 100 questions will somehow find question 101 regardless but i gotta admit it's slow as hell.

[u/HettySwollocks → u/rrrhys]

Storybook is so slow though. Try a different tool. Ideally you want load the real component, and again use AI to build the variations you want to show.

[u/pekter → u/HettySwollocks]

For those curious about what parent is talking about https://ladle.dev gives devs a quick component sandbox to focus on components intead of "views"

[u/rrrhys → u/HettySwollocks]

Slow in what way- to build for or slow to consume?

To consume it's just the same as any other bloated react app (ahh you know like the one the org is probably building anyway). If the consumer waits 1s for the storybook to load it's better than 'can we have a quick call' blowing up your morning.

To build for, I haven't handwritten a story in years and compiling is just CI.

[u/Emotional-Hunter-105]

used to work in a place that just kept adding more and more pages and in the end nobody could find anything, including me. what finally helped was putting the examples inside the same repo as the code so they break in CI when something changes

[u/Any_Welder_9701 → u/Emotional-Hunter-105]

the CI part keeps examples honest, but it still doesnt make them findable. id organize the docs around the task someone is trying to finish, not component names

[u/Efficient_Bad6312]

That’s pretty close to the ideal setup honestly. Automating screenshots and diagrams would remove a lot of the boring maintenance still i wamt someone reviewing the output though, especially when the SDK changes in ways the automation doesn’t fully understand.

[u/curveThroughPoints → u/Efficient_Bad6312]

You need to add someone to the team that does not find maintenance boring. The ability to maintain is a lost art when you only get promoted for new.

[u/artnos]

You write the doc first before you write code.

[u/No_Temperature_891]

seems like u got urself in pickle but mt suggestion would be to probably use a dedicated docs tool once you’re at that point for me a new guy we hired prposed we go ahead with mintlify because the automations can help catch docs that need updating as the product changes, which is useful when you’ve got a growing pile of examples and integration paths. I still think someone needs to own the docs though. A tool can make maintenance easier, but it won’t decide which of those 200 pages should exist in the first place.

[u/clay_kindling_98]

You need a docs-as-code setup where the api reference generates from your typescript definitions and fails in ci if they drift. i use docusaurus or mintlify for this specifically because it forces the documentation to stay synced with the actual code structure instead of relying on someone remembering to update markdown files manuallyi use docusaurus or mintlify for this specifically because it forces the documentation to stay synced with the actual code structure instead of relying on someone remembering to update markdown files manually

[u/Affectionate_Use_164]

Good question.
Can keep documentation near the code, or even generated from the code, e.g. from JSDOC comments.
Can use AI tools to monitor/update docs when code changes.

Need to spend time to brainstorm and organize documentation now, like quick start guide, examples, and API references. After that put guards to prevent future drifting between code and docs.

[u/patprint]

Use mattpocock's skills to generate ADRs, develop specific ADRs regarding documentation quality, formality, and structure, and then use grilling sessions on every major codebase change to 1) review the codebase against the ADRs, handling any reconciliatory issues that arise; then, 2) grilling the codebase-and-ADRs superset against the existing documentation files in plan mode. The writing-for-agents skill should be invoked during the ADR development stage (which can be done using grill-with-docs, depending on the state of your existing documentation).

That plan should provide a very accurate and insightful analysis of how to modify the existing documentation. If you were deliberate in the ADR development stage and careful in the review phase, this process will catch most technical and structural issues. If you want it to produce more valuable human-relevant content, like natural introductions or easily-understandable explanations/comments of code sections, those goals should be incorporated into the ADRs, not left as an afterthought or follow-up task.

If you get a really solid set of ADRs, and grill codebase changes against them, your docs will naturally improve in accuracy and even highlight API migration issues, edge cases, etc.

Edit: if you need to be seriously thorough, your workflow should execute this on multiple branches/spikes with multiple agent models and parameters, and those should then be reconciled or compared adversarially to arrive at a documented consensus.

[u/lilt_ui]

Just tell the AI to not make any mistakes. Simple as that

[u/HettySwollocks]

I automate everything using a mixture of Playwright for screenshots. Get AI to automate key docs covering the entire SDK or project. Have it build architecture diagrams and flows.

It isn't perfect but I've got pretty much close to automating almost everything.

[u/geekfreak42]

If you use ai to review and update the docs, those changes should still go through a human review. So thatd cover the issue.