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

Move entries from api-guide page into their own distinct pages in /api-reference #203

Open
wants to merge 2 commits into
base: main
Choose a base branch
from

Conversation

tburny
Copy link
Contributor

@tburny tburny commented Mar 1, 2025

With a growing number of types and definitions, the API reference page becomes quite lengthy and it is easy getting lost while reading.

Changes:

  • The api-guide.md contents were moved into separate pages for Event, Command, EventStore and CommandHandler.
  • Each API reference item now is its own item in the sidebar (easy to find)
  • Add overview page at /api-reference. Clicking the "Next" link links to /api-reference/event as first page from the navigation
  • For each page, use a similar structure of: Description text ("Overview"), _Usage, Definition, See also. This "template" structure makes it easier to find the thing one is looking for at first glance. The sidebar nav on the right supports this (looks quite the "same" for Event, Command, Event Handler and Command Handler)
  • Keep the api-docs.md page and link to the moved contents, as Cool URIs dont change.

Open items (tbd):

  • [] Naming: Is it command-handler.md or commandhandler.md? I am favouring the second as reference to the type name in the code
  • [] Decide on order of Usage and Definition. While I think it is more convenient to skip the code definitions and see "how can I use it" first, it feels a bit strange like in "First definition, then usage".

tburny added 2 commits March 1, 2025 03:16
This change seperates the sections of api-docs.md into one file per type. This allows easier targeted skimming of the reference documentation without feeling lost.
…ake it even easier to navigate their contents
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant