Hi folks, I’ve converted the Graphviz docs website (graphviz.org) to Docsy, a theme/framework for technical documentation. It’s not perfect yet, but it’s ready to get some eyes on it for some feedback.
The topbar and case-sensitivity issues should be fixed now: /Resources and /Gallery now work after building on Linux. I’ve even got it building on GitLab pages, same as the production site. And the site should
I confess I’m still sort of confused by the navigation. When you hit the homepage, there’s a “Documentation” link in the header, the left nav pane, the right nav pane, and the trailer of the page. 3 out of 4 of these go to the same place. Maybe this is intentional?
I’m maybe an unusual web consumer, in that both my phone and my laptop have small screens, so I’m distressed by every extra pane that takes away space from the main content area. This isn’t an issue here, because this page gracefully adapts to small displays, but when I do have a larger screen I’m wondering why there are so many panes.
I hope I don’t sound overly critical; I really like the new design. Just trying to learn how to navigate it.
I like the new design a lot. It looks modern and fresh. If I have to complain about something it’s that I don’t like words written in all-capitals because they’re harder to read, so perhaps the GRAPHVIZ name in the upper left could be Graphviz instead? Unless there’s some standard that we want to conform to of course.
Thanks for the feedback. Just had a moment to move this forward a little.
I confess I’m still sort of confused by the navigation. When you hit the homepage, there’s a “Documentation” link in the header, the left nav pane, the right nav pane, and the trailer of the page. 3 out of 4 of these go to the same place. Maybe this is intentional?
Yes, this is probably a bit too many links
The header should link to top-level sections of the site. I only have three for now: Documentation/Gallery/GitLab. You could imagine a ‘Home/Download/Documentation/Gallery/GitLab’ split instead in future, or perhaps some other split? The split I went with is fairly arbitrary, focussed on migrating to Docsy before making more dramatic changes.
The left nav should go to specific pages.
The right nav should go to headings within the page. I’m really looking forward to shipping a right-hand-side table of contents for huge pages like attrs.html, I think that’ll help our users a bunch skipping to the part of the page they’re interested in (attrs.html doesn’t have table of contents in this v1, but I have a series of patches to follow this that will make it work).
We probably don’t need another ‘Documentation’ heading inside the home page text now; getting rid of that would get rid of this link.
The trailer of the page defaults to linking to subpages of this section. We can turn this off if it doesn’t make sense with a field in the YAML front-matter.
If I have to complain about something it’s that I don’t like words written in all-capitals because they’re harder to read, so perhaps the GRAPHVIZ name in the upper left could be Graphviz instead?
Yep I don’t like the all-caps much either. And a bunch of other Docsy sites (e.g. https://grpc.io/docs/) have overridden this to not be in all-caps, so we should too.
I just want to say that I’ve just started to use Graphviz a little in my current assignment and I enjoy the new documentation immensely. It’s so much easier to navigate now. Thanks a lot for doing this work.
