You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
What is the current behavior?
We are currently utilizing sphinx for documentation. Each sub-project in DESDEO has currently its own implementation of sphinx-based documentation. Each one of these needs to be always manually modified. Moreover, our documentation style should be more clearly structured.
Describe the solution you'd like
We should move to a simpler tool and adopt a clear (and tested) documentation structure. We have previously already discussed MkDocs, which is a promising candidate for an alternative tool.
As for the structure of the documentation, we should follow the diataxis philosophy.
What is the motivation/use case for changing the behavior?
Sphinx is complicated. With a simpler tool, the bar to write and contribute to the documentation will be lowered. With a clear structure for the documentation, we, and users, have also a clearer picture of where to find relevant content. Diataxis is followed by other projects as well, it is tried and tested, and will meet the expectations of many users when it comes to documentation.
Describe alternatives you've considered
Sphinx has been the only real alternative we have considered and used. It works, but the features it offers at the cost of added complexity are not justified for our use-case.
Additional context
This is related to the structure of the project. With a monolithic structure (discussed in [IDEA] New project structure for DESDEO #73 ), we will also end up with a single documentation to work on, which facilitates things a lot.
The text was updated successfully, but these errors were encountered:
What is the current behavior?
We are currently utilizing sphinx for documentation. Each sub-project in DESDEO has currently its own implementation of sphinx-based documentation. Each one of these needs to be always manually modified. Moreover, our documentation style should be more clearly structured.
Describe the solution you'd like
We should move to a simpler tool and adopt a clear (and tested) documentation structure. We have previously already discussed MkDocs, which is a promising candidate for an alternative tool.
As for the structure of the documentation, we should follow the diataxis philosophy.
What is the motivation/use case for changing the behavior?
Sphinx is complicated. With a simpler tool, the bar to write and contribute to the documentation will be lowered. With a clear structure for the documentation, we, and users, have also a clearer picture of where to find relevant content. Diataxis is followed by other projects as well, it is tried and tested, and will meet the expectations of many users when it comes to documentation.
Describe alternatives you've considered
Sphinx has been the only real alternative we have considered and used. It works, but the features it offers at the cost of added complexity are not justified for our use-case.
Additional context
This is related to the structure of the project. With a monolithic structure (discussed in [IDEA] New project structure for DESDEO #73 ), we will also end up with a single documentation to work on, which facilitates things a lot.
The text was updated successfully, but these errors were encountered: