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

Migrate/add an API documentation site based on MkDocs #148

Draft
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

oprypin
Copy link
Member

@oprypin oprypin commented Mar 2, 2021

Includes version selector and auto-deployment to GitHub Pages.
The URLs are fully backwards compatible.

Preview: https://oprypin.github.io/crystal-db/api/

The main thing that's up for discussion is the categorization on the left hand side. I thought it added a lot to the usability, but it's manual and done by me without any familiarity with "crystal-db", so maybe the categories need tweaking.

Includes version selector and auto-deployment to GitHub Pages
@straight-shoota
Copy link
Member

Looks awesome 👍

That manual editing of SUMMARY.md is unfortunate, but I agree that having these sections in the navigation is a great enhancement. So I'd prefer to rather have that instead of missing out on the structuring.

For the future we could consider integrating section tagging in the doc generator syntax to remove the gap between structure and content.

@z64
Copy link

z64 commented Mar 23, 2021

I'm sorry if this is too critical, but I don't think this frontend is ready yet for documenting general code.

Overall presentation The overall presentation feels like a step backwards in design. The headers are hard to read with low contrast and multiple font sizes. The body being in this quote block looking style gives a structure that doesn't feel apropriate; it feels more like a blog.

image

Compare to crystal docs, which has very distinct headers that gives all the structure it needs:

image

Another comparison, where we are missing the concise summary that more quickly helps me find my way. I am often searching for something first before learning about it - without the summary there is a lot more scanning / noise to go through.

image

image

I'm aware of the right-side ToC, but I don't feel this is adequate. We lose the short summary, at least.

Search

You can not search for methods with the same syntax that the compiler docgen has:

image

Maybe there is some other trick I don't know, but I have to expand the list and what I want is very far down:

image

Again, with crystal docs what I am looking for is the third item:

image

ToC on smaller breakpoint

If you open https://oprypin.github.io/crystal-db/api/ and are on a small breakpoint, you get this in the ToC bar. Until I realized I had to click the arrow on the upper left, I thought something was broken.. Can this UX be improved? We still have a ton of real estate on the sidebar, but at least a better button would be nice, or a text hint - I thought it was just going to close the sidebar.

image

There's some other things, but these were the biggest issues I found with this. The organized sidebar is nice. But in my opinion, the design problems here don't make it worth it. In the current state, I would rather see crystal docs improved to allow sidebar organization.

If we host them both then I guess that is fine, but this is 👎 from me if we are considering replacing the current docgen.

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.

3 participants