Improving Documentation

[WillieCubed]

Hi, I've been using Koin for a few months now, and I've noticed that the documentation has a few quirks that made it a little difficult to read and some room for improvement to make the docs easier to browse/find specific information.

To make it more readable, I'd like to submit a pull request overhauling the documentation on the website to:

• Restructure the reference to be easier to scan/find information
• Include more detailed tutorials and real-world usage examples
• Deduplicate information (e.g. KMP dependency injection reference and KMP quickstart)

I believe we can make the documentation more accessible to those who aren't as familiar with dependency injection, especially in a Kotlin context. I'd like to take a similar approach to Android's documentation on Hilt, where it explains some of the dependency injection basics with examples and including as many reusable, copy/paste-able snippets as possible.

Set-up Improvements

The docs should have a consolidated tutorial page detailing the most common Koin setup with different sections for specific artifacts (e.g. Compose, Koin). This should be in addition to specific reference pages for configuring Koin for different platforms in more detail.

Koin's main setup docs include a mention about version catalogs, but later in the same page, code snippets still use manual version definitions. The docs should be opinionated about using the build of materials as the standard way to set up Koin and remove the dedicated section at the bottom, replacing it with a link to more info about Gradle BOMs.

Little things

The setup docs are inconsistent in places. For example, some parts use Gradle KTS build scripts, while others still use the Groovy DSL. Here are a few examples of configuration docs that can be improved:

• Kotlin tutorial
• Android - Jetpack Compose

Throughout all the docs, there are a few sentences with grammatical errors that can be cleaned up (e.g. capitalized, rewritten) to make them read more professionally and with more clarity.

The formatting for some Markdown admonitions is broken, like this one.

Koin Annotations

Koin Annotations exists in the same docs as the Koin core libraries, but depending on the direction of the library, we should be opinionated on using Koin Annotations as the main way of using Koin and including information on how to perform manual injection as needed. Being opinionated will make providing support and documentation for the library a little easier in the long-term and make it less confusing for developers searching for answers on how to solve their problems when using the library.

Nonetheless, the interoperability between Koin Annotations and the Koin core library is unclear. For a new library user, they should know how the two are similar and how they differ. We can explicitly include snippets that show when the APIs are functionally identical:

// Tag your component to declare a definition
@Single
class MyComponent

val myModule: Module = module {
    single { MyComponent() }
}

Multiplatform First

For any mentions of Koin being used in a multiplatform environment, we should update the docs to make make usage more explicit. For example, the setup docs for Koin with Compose Multiplatform have this snippet:

dependencies {
    implementation("io.insert-koin:koin-compose:$koin_version")
    implementation("io.insert-koin:koin-compose-viewmodel:$koin_version")
    implementation("io.insert-koin:koin-compose-viewmodel-navigation:$koin_version")
}

We should rewrite configuration blocks like this to avoid confusion for KMP setup:

kotlin {
    // ...

    sourceSets {
        commonMain.dependencies {
            // Using version catalogs
            implementation(project.dependencies.platform(libs.koin.bom))
            implementation("io.insert-koin:koin-compose")
            implementation("io.insert-koin:koin-compose-viewmodel")
            implementation("io.insert-koin:koin-compose-viewmodel-navigation")
        }
    }

On another note, it may be worth considering a KMP-first approach that doesn't make any initial assumptions about how you're using Koin. There's currently a dedicated Android section for configuring Koin, which should be preserved, but having some cross-platform examples (e.g. for JVM/desktop and wasmJs) for common use cases would be very useful.

There are a lot of little changes that I believe would improve the quality of life of the docs, so I'd be glad to create a draft PR with more details. I see that there's a roadmap that includes some of my observations, so how should I approach this @arnaudgiuliani? I'd really like to contribute to the project!