Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Conversation

tburny
Copy link
Collaborator

@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
See more context in [getting started guide](./getting-started.md#events)

<<< @./../packages/emmett/src/typing/event.ts
[Moved here](/api-reference/event)
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

QUESTION: Do we need to keep this file?

@oskardudycz
Copy link
Collaborator

Regarding open items:

As mentioned on Discord, I think I'd prefer snake or kebab case, as those files will be mapped to URLs and that will make them easier to find, and potentially improve SEO. Yet I'm not strong on that, as we can always later on change it and add url rewrites.

Regarding order of Usage and Definition. I like to teach in a way that I give the problem statement, then basic solution, and then, so:

  1. Problem statement,
  2. Potential solution so usage,
  3. Explaining why this solution is recommended and definition.

But I'm also not strong on that. That works for me, as it helps to keep readers motivated to read. A bit of storytelling technique is always good. If we have a full definition first, then the solution, many people immediately scroll down.

Still, we can also follow Diataxis' advice and use different patterns depending on the intention.

In general, what you did seems legit to me.

@oskardudycz
Copy link
Collaborator

Ah, @tburny could you run npm run fix to clean up some linter issues with md files?

@oskardudycz oskardudycz added documentation Improvements or additions to documentation enhancement New feature or request labels Mar 1, 2025
@oskardudycz oskardudycz modified the milestones: 0.34.0, 0.35.0 Mar 1, 2025
@tburny
Copy link
Collaborator Author

tburny commented Mar 2, 2025

I fixed the issues and kept things as-is, for the aforementioned reasons.

@oskardudycz oskardudycz merged commit 4853287 into event-driven-io:main Mar 2, 2025
1 check passed
@oskardudycz
Copy link
Collaborator

Thanks @tburny !

@tburny tburny deleted the refactor/api-reference-section branch March 2, 2025 22:33
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 enhancement New feature or request
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants