-
Notifications
You must be signed in to change notification settings - Fork 7
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
Documentation M1A #3
Comments
A first interesting question could be how our documentation infrastructure should look like. With the previous POC we looked into https://antora.org/, which allows to build documentation that is spread across multiple repositories (e.g. https://github.com/restatedev/restate, https://github.com/restatedev/sdk-typescript, etc.). See restatedev/documentation for more details. This allowed to keep the documentation close to the code. As markup language it uses AsciiDoc which seems to be a bit more expressive than Markdown (e.g. it is doable to include code snippets from source files that are part of the CI pipeline so that they are checked to not go out of date). Admittedly, AsciiDoc has a steeper learning curve than Markdown. Antora is also more complex to set up than a single documentation repository which contains Markdown and is built somewhere. |
@tillrohrmann I would be up for continuing to use antora. For basic formatting, antora is more or less similar to markdown and we have all the infra for that already setted up, we just need to change the repo names we point to. |
Here is an example of the previous docs that were built by the documentation repository: docs-1.0.0-alpha.4.tar.gz |
@gvdongen do we want to move this issue to done? If not, are there other documentation tasks missing we want to do for this milestone? |
Closing this issue as done. Thanks everyone for creating the great documentation! |
Umbrella issue collecting the different documentation related issues:
Tasks
The text was updated successfully, but these errors were encountered: