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

Antora docs initial work #11

Merged
merged 1 commit into from
Jan 13, 2025
Merged

Antora docs initial work #11

merged 1 commit into from
Jan 13, 2025

Conversation

ozgunozerk
Copy link
Collaborator

Implements #10

This PR lays the ground work for antora docs.

The structure I envisioned for the docs is based on the following principles:

  • we shouldn't document anything that is under the responsibility of Stellar (if we think their documentation could be improved, we should contribute to them instead of creating duplications
  • scope of our documentation should only cover what we are building (our library, and our tools if we develop any in the future)
  • currently, the outline is based on Token Standards

Note: I'm indecisive on whether to put a document on Design Decisions. Due to the following reasons:

  • we explain the reasonings behind our design decisions in our code as inline documentation. Design decisions generally make more sense with the context of code is also present (inline docs makes perfect sense for this imo). Having these explanations also present in antora docs may not make much sense, because:
    • duplication of the content across inline docs and antora docs
    • context of code is not that convenient to reach from antora docs compared to a code editor
  • if our design decisions change in the future, changing the inline docs is quite intuitive, we probably wouldn't forget. But having to also keep antora docs up to date w.r.t these potential changes might become a burden, and we may forget to do so from time to time.

So, I decided against having Design Decisions, but I'm 100% open to discuss it if there are other points that I've missed 👍

@ozgunozerk ozgunozerk added the documentation Improvements or additions to documentation label Jan 13, 2025
@ozgunozerk ozgunozerk requested a review from brozorec January 13, 2025 11:20
@ozgunozerk ozgunozerk self-assigned this Jan 13, 2025
@brozorec
Copy link
Collaborator

LGTM

Regarding Design Decisions I agree with you that it better goes to the dedicated module/functions. A good candidate for such a section can become content that we find ourselves repeating in several places. So I guess we don't need it for the moment.

@ozgunozerk ozgunozerk merged commit 5ce5067 into main Jan 13, 2025
2 checks passed
@ozgunozerk ozgunozerk deleted the antora-docs branch January 13, 2025 12:43
@ozgunozerk ozgunozerk linked an issue Jan 20, 2025 that may be closed by this pull request
1 task
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
Status: Done
Development

Successfully merging this pull request may close these issues.

🏗️ [Core Feature]: Setup Antora Docs for our repository
2 participants