Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Move Tutorial and Guides Docs To (a) Separate Module(s)/Repository/ies #7973

Open
khajavi opened this issue Apr 1, 2023 · 0 comments
Open
Labels
documentation Documentation improvements

Comments

@khajavi
Copy link
Member

khajavi commented Apr 1, 2023

It is challenging and requires a significant amount of time to keep tutorials and guides up-to-date within the ZIO repository. Why? because:

  1. 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.
  2. 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:

  1. 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.

  2. 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.

  3. 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.

@khajavi khajavi added the documentation Documentation improvements label Apr 1, 2023
@khajavi khajavi changed the title Separate Tutorial and Guides Docs To (a) Separate Repository/ies Move Tutorial and Guides Docs To (a) Separate Repository/ies Apr 1, 2023
@khajavi khajavi changed the title Move Tutorial and Guides Docs To (a) Separate Repository/ies Move Tutorial and Guides Docs To (a) Separate Module(s)/Repository/ies Apr 2, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Documentation improvements
Projects
None yet
Development

No branches or pull requests

1 participant