Summary

The goal of this issue is to propose a first documentation concept to iterate on and start a discussion around this topic.

Motivation

As the Project grows it would be helpful to have a good documentation, especially for new contributors and users.
The documentation has to contain all neccessary information while still beeing easy to use and maintain.

Technical Design

TL;DR
Create a seperate repository "OpenDevin/OpenDevinDocs" for documentation, containing autogenerated code documentation and manually created parts (Overview, architecture, examples)

Generation and content
The documentation should at least contain the following contents:

• High-level project overview
• Installation instructions, How-To Guide, Examples
• Architectural diagrams
• API documentation
• Generated code documentation

This means documentation will consist of two parts: An autogenerated code documentation Part which is generated by GitHub actions on every commit/PR and a part for which has to be maintained manually, but less frequently.

Versioning / Repository
The documentation should be stored in a seperate repository (e.g. OpenDevin/OpenDevinDocs)
This enables tracking documentation-related issues separately, keeping the main repository focused on development.
It would also be possible to implement the same branch concept as in the code repository by automatically creating a docs branch for each code branch.

Separation between Frontend and Backend
Pro seperation: Frontend and backend use very different technology stacks. A seperation allows it to use better suited tools for each part.
Con seperation: Frontend and Backend are part of the same project, so the documentation should also consider both parts for a better understanding of the project as a whole.
Proposal: Store frontend and backend docs in the same repository with a root-level separation (similar to the code repository). Then docs for frontend and backend can be generated separately and maybe can be tied together with an index site for navigation between both parts.

Tooling
For Backend: Use Sphinx due to its wide usage and extensive configurability.
For Frontend: TBD.

Documentation Format
HTML for best readability/design and compatibility for hosting on various platforms.

Hosting
Sphinx generates HTML files which can be hosted for example on GitHub Pages or readthedocs.

Alternatives to Consider

Additional Context

This page provides a good guideline on the content of a project documentation
https://coderefinery.github.io/documentation/wishlist/