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

Documentation M1A #3

Closed
8 tasks done
slinkydeveloper opened this issue Feb 28, 2023 · 5 comments
Closed
8 tasks done

Documentation M1A #3

slinkydeveloper opened this issue Feb 28, 2023 · 5 comments
Assignees
Labels
documentation Improvements or additions to documentation

Comments

@slinkydeveloper
Copy link
Contributor

slinkydeveloper commented Feb 28, 2023

Umbrella issue collecting the different documentation related issues:

Tasks

Preview Give feedback
  1. documentation
    tillrohrmann
  2. aws-lambda-endpoint
    gvdongen
  3. documentation
    slinkydeveloper
  4. documentation
    slinkydeveloper
  5. 0 of 1
    documentation
    slinkydeveloper
  6. documentation
    slinkydeveloper
  7. documentation
    slinkydeveloper
  8. documentation
    jackkleeman
@slinkydeveloper slinkydeveloper added the documentation Improvements or additions to documentation label Feb 28, 2023
@tillrohrmann
Copy link
Contributor

tillrohrmann commented Apr 24, 2023

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.

@slinkydeveloper
Copy link
Contributor Author

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

@tillrohrmann
Copy link
Contributor

Here is an example of the previous docs that were built by the documentation repository: docs-1.0.0-alpha.4.tar.gz

@tillrohrmann
Copy link
Contributor

@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?

@tillrohrmann
Copy link
Contributor

Closing this issue as done. Thanks everyone for creating the great documentation!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

No branches or pull requests

3 participants