Do you have any opinions on how documentation shou...

# library-development

[CLOVIS]

Do you have any opinions on how documentation should be structured?

At the moment, I often follow a separation in three sections:
• Getting started: short, direct tutorials, that demonstrate how to achieve a very specific goal (eg. setup boilerplate)
• Features: dedicated pages to each feature type (e.g. time control in Prepared is split into three different modules that add different functionality, but it's a single Features page that shows how everything fits together)
• Reference: exhaustive documentation for each specific method, with the intent that users navigate it when they want information on a specific thing
In multiple of my projects, I think this distinction works fairly well. However, in KtMongo, there is additional information I want to show, and I'm not sure how to organize it.
• There will be two migration guides, which may have subpages. For now, they're in Getting started, but I'm not sure that makes sense.
• There are four versions of the library (blocking, suspending, multiplatform, Java compat) and the configuration is different, but the features are mostly identical
• There are multiple compatible serialization libraries, which may impact other features
How would you organize all of this?

[Javier]

Human or AI consumers :P

TBH, I found really pleasant that Cloudflare exposed multiple MCP servers only for their documentation so the structure is “irrelevant” due to you can just do the question and get the answer with examples or whatever you want without having to dig.

[CLOVIS]

Human consumers.

[mbonnin]

I don't really have an answer but SQLDelight comes to mind: https://sqldelight.github.io/sqldelight/

[mbonnin]

They have blocking vs non-blocking and different docs for different dialects

[mbonnin]

That being said, I initially found SQLDelight docs being a bit hard to navigate

[mbonnin]

No silver bullet I guess

[jessewilson]

Code listings with tabs for different variants. Ive seen Java/Kotlin splits with copy-pastable examples of each; you could do 4 tabs for your 4 variants?

[jessewilson]

How we did it in OkHttp:
https://square.github.io/okhttp/recipes/#__tabbed_1_1

[brandonmcansh]

Similar to how I setup docs for trace https://docs.traceclick.io/sdk/android/