Description
It is challenging and requires a significant amount of time to keep tutorials and guides up-to-date within the ZIO repository. Why? because:
- All docs stuff (references, guides, tutorials, quickstarts, ...) have the same sets of library dependencies. This causes a huge amount of updates to update just one article. For example, to update one article's zio-http dependency, we need to update all other docs.
- Confliction of articles dependencies, some articles are not ready to update, and we need to keep them with old dependency versions, this is where updating a specific part of docs conflicts with other parts.
I have come up with three solutions/options:
-
It would be more efficient to transfer them to a distinct repository. For example, we can have a repo named "ZIO Quickstarts" and include both code and docs in one place for all tutorials and quickstarts.
-
It also would be better to move tutorials and guides to their related repos, for example, the "Tutorial: How to Make a ZIO Application Configurable?" should be moved to "ZIO Config" project. So by any change to the library itself, we can encourage library authors to update the docs, including guides and tutorials.
-
We can move each article to a separate submodule in the zio repo, so each module has its own set of dependencies.
To begin, I believe the last solution is a good option. After separating all the modules, we can consider the other solutions that were discussed previously.