Skip to content

DOCS: generate smaller tables for feature matrix#3579

Closed
chicks-net wants to merge 21 commits intoStackExchange:mainfrom
chicks-net:chicks/split-provider-table
Closed

DOCS: generate smaller tables for feature matrix#3579
chicks-net wants to merge 21 commits intoStackExchange:mainfrom
chicks-net:chicks/split-provider-table

Conversation

@chicks-net
Copy link
Copy Markdown
Collaborator

@chicks-net chicks-net commented May 22, 2025

context

#3305 notes that the provider feature table does not display well in the GitBook-based documentation site.

This has also been brought up in a couple of the monthly live calls.

progress

This PR splits the features into different groups for different tables. It generates the tables with H3 headings. The changes to the generator and the documentation are included in this PR.

Some additions to /.gitignore are also included.

future

Updating individual provider pages (#3584) is coming next.

Maybe file some bug reports with GitBook for the issues found.

prior "discussion" questions

  • Does this split of things into three tables seem reasonable?
    • This seems to be the easiest fix. Other things would require get patches in GitBook.
  • Would it be better to leave the DomainModifiers out of the top level table and add that information into individual provider pages (with more automation of course)?
    • This will happen in a future PR
  • If we're going with 3 tables at the top level, would there be a better grouping of the domain modifiers or any of it?
    • This grouping has been improved.

@eliheady
Copy link
Copy Markdown
Contributor

I don't have much of an opinion either way on keeping the scrolling table or breaking it up. Using three tables would solve the horizontal scrolling problem at least.

As for grouping, maybe the RR types should be rearranged to keep related types (and meta-types) together. For instance, AutoDNSSEC, DS, DNSKEY would be good to put together.

I think the data should definitely be included on each provider page as a supported features table with just two columns: feature and green/red/? status.

@chicks-net
Copy link
Copy Markdown
Collaborator Author

I don't have much of an opinion either way on keeping the scrolling table or breaking it up. Using three tables would solve the horizontal scrolling problem at least.

😁

As for grouping, maybe the RR types should be rearranged to keep related types (and meta-types) together. For instance, AutoDNSSEC, DS, DNSKEY would be good to put together.

That sounds good. I will try that.

I think the data should definitely be included on each provider page as a supported features table with just two columns: feature and green/red/? status.

This was my original goal and I still think it is a great idea. I'm guessing that will be a different PR though. Fixing the existing table has helped me understand what I will need to do that.

I will clean up this code and request more feedback once it is ready for a review. (It will probably be next week, since we're babysitting this weekend.)

@chicks-net chicks-net requested a review from eliheady May 23, 2025 01:56
@chicks-net chicks-net marked this pull request as ready for review May 23, 2025 01:56
@chicks-net
Copy link
Copy Markdown
Collaborator Author

I've moved this out of draft - please review.

Looking at the preview in GitBook is encouraging, but I'm guessing we should aim for 4 tables. I'll work on that next.

@eliheady
Copy link
Copy Markdown
Contributor

I'm not sure this is better than the side-scrolling table, but it's not really worse either. It's just a lot of data to fit. I wish we had better control over the Gitbook layout and styles so something like sticky headers and columns or even column filtering could be used. I found an interesting hack using SVG to stuff css styles that works in GitHub markdown rendering. I didn't try it in Gitbook.

If there are to be multiple tables, the 'Table 1', 'Table 2' section headings should be omitted or used to highlight which features are included in the tables (not sure how to best summarize that for a terse heading though).

@chicks-net
Copy link
Copy Markdown
Collaborator Author

I'm working in https://gist.github.com/chicks-net/e3533d8a766013895f917dc4a22b7761 to categorize all of the columns and see if i can find a more logical organization. Suggestions are welcomed.

@chicks-net
Copy link
Copy Markdown
Collaborator Author

New question: do any of the DomainModifiers make sense for registry-only providers, like OpenSRS? Could we presume unimplemented for all of those? Or should there be a new category of "not applicable" with an emoji like ✖️ ?

@chicks-net
Copy link
Copy Markdown
Collaborator Author

chicks-net commented May 24, 2025

preview is looking good to me. 6 tables looks ok. The "DNS extensions" table has the most columns and the most word wrapping, but it is still pretty readable.

Non-blocking issue: Does anybody know why GitBook doesn't handle Markdown paragraphs well? It was keeping the line endings from the file and not flowing the paragraph unless i had the whole paragraph on one line. GitBook says they support Commonmark which is pretty clear about how paragraphs in Markdown should work.

@chicks-net
Copy link
Copy Markdown
Collaborator Author

yet another preview to document the dual-host column. For some reason it tries to link back to github - which 404s since this is not merged yet.

This also effects the Concurrency Verified column on the live site. So it looks like a GitBook bug and I'm not sure why GitBook is acting this way. I'll see if I can fix this. If not, I'll make a new github issue for this problem.

@tlimoncelli
Copy link
Copy Markdown
Contributor

(Been a busy couple days... just catching up!)

Wow! I saw the latest preview! Looks SO much better!

The only suggestion I have so far is on the DNSSEC table... the AUTODNSSEC columns should be first.

Can we make the table columns more narrow? (I'm guessing not, but I thought I'd ask)

@chicks-net
Copy link
Copy Markdown
Collaborator Author

(Been a busy couple days... just catching up!)

No worries! I wasn't expecting to be this far along before the weekend.

Wow! I saw the latest preview! Looks SO much better!

Thank you, thank you.

The only suggestion I have so far is on the DNSSEC table... the AUTODNSSEC columns should be first.

Agreed! Done in de66cf2 .

Can we make the table columns more narrow? (I'm guessing not, but I thought I'd ask)

Reading https://gitbook.com/docs/creating-content/blocks/table makes it sound like this should be possible, but they don't explain how this works out at the Markdown level. I looked for other sites that use gitbook, but all of them that I've seen use basic table syntax.

(I'm very new to GitBook, but I'm boggled by how much of their documentation is thin on the source code side. That's really not what I'd expect for something with git in the name.)

So we're left with the old school techniques: removing characters from the titles, splitting up a title into multiple words, etc. I don't think the x/check/? cells are causing the columns to be wider.

@eliheady
Copy link
Copy Markdown
Contributor

This is looking great @chicks-net ! I think the way you have categorized and broken up the tables makes it much easier to find the bit of information needed with less noise to ignore.

@chicks-net
Copy link
Copy Markdown
Collaborator Author

This is looking great @chicks-net ! I think the way you have categorized and broken up the tables makes it much easier to find the bit of information needed with less noise to ignore.

Thanks for your comments, encouragement, and code. 🙏 It was fun to do some golang again after focusing on other languages recently.

I also left https://gist.github.com/chicks-net/1b85b88851812075130bfc67d465bb3c out of this PR, but if anyone is interested in seeing how helpful just can be, this is a very small example. My personal web sites have justfiles that have grown much larger, and it is still manageable. 😁

@tlimoncelli
Copy link
Copy Markdown
Contributor

LGTM! Please rebase and I'll merge.

@chicks-net
Copy link
Copy Markdown
Collaborator Author

Gave up on fixing merge conflicts and opened #3589 .

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants