erickguan commented on issue #5755:
URL: https://github.com/apache/opendal/issues/5755#issuecomment-2779871291
What do you think about adding documentation about service configurations?
I propose:
- Add a "Services" section on the website.
- Populate each service’s documentation from docs.md.
- Move Rust builder-related code to each builder.
Advantages:
- Enhanced Visibility: Developers can quickly understand which features each
service supports.
- Consistent Convention: Provides a simple, uniform approach for writing
`docs.md`.
- Cross-Linking: Bindings documentation can easily link to the services
documentation, improving navigation and context.
Disadvantages:
- Fragmentation: There’s a risk of documentation being split between a
central services section and language-specific bindings, which might lead to
inconsistencies.
- Maintenance Overhead: Keeping the services documentation up to date in
both the central section and within bindings might require extra effort.
- Indirection Complexity: If we choose not to include service documentation
in bindings, we will add an extra layer of indirection. The indirection could
make navigation more confusing if not managed properly.
Open Questions:
- How should a binding’s documentation incorporate the services
documentation?
- Will the added indirection cause usability or navigation issues?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscr...@opendal.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
