Greetings. I would like to discuss if it makes sense to significantly revise the content and even structure of the website. The website could provide better guidance to put this project into a broader context, direct different kinds of visitors to appropriate areas of the website, and highlight common ways of using this software.
IMHO the website is already rather good. We need instead an updated/better documentation (there are still docs printed in 2015 for 2.38 version) and a full user’s guide, for tools and add-ons too. Many parameters are still unexplained or not well defined
Anyway a website revision can be useful, also for search engines
These are good observations.
One of my projects now is reverse-engineering osage, by reading the code. I believe there are, literally, 0 examples to be found, neither in graphviz nor anywhere else on the inter web.
@scnorth Thank you for starting this discussion. I agree that there’s an opportunity to update improve the website, and I’d love to help.
I see that the source code for the website is published at https://gitlab.com/graphviz/graphviz.gitlab.io. Would you be interested in PRs addressing the currently open issues?
Beyond that, what would be the most constructive way to send feedback about the current site? Would you prefer filing issues, or discussing it on this thread first?
Hi there. I’ve been making a few improvements to the docs lately, and I have some ideas.
I’ll jot some of them down here:
- I’d like to have a lot more examples on the attrs.html page, ideally with source code next to the rendered SVG output. I’m particularly inspired by the Ansible documentation which has many examples for every module that you can usually copy/paste. Issue Link.
- This may necessiate breaking attrs.html up into a page per attribute, with examples of how to use it. It might be too large if we don’t break it up (this might be controversial - we can always have both).
- I think there’s a big gap we could fill to add a tutorial or Getting Started page, onboarding people onto how to use the most frequently useful features. attrs.html is extremely long and you don’t want to dig through all of that on your first time. Issue Link
- The gallery could use an update, the HTML is pretty old, and I think it could use some more examples too. Issue Link
- I would love to have a “Try Graphviz in your browser” – much like https://play.golang.org/p/MAohLsrz7JQ, https://www.python.org/ (“Try Python in your browser”), https://try.ruby-lang.org/, https://kotlinlang.org/, https://www.scala-lang.org/ all have linked from the homepage. Graphviz is a programming language and we can learn from the UX of other programming language websites, that trying the language is one of the first things users want to do. Issue Link.
- More on the above, it would be fantastic to have an interactive tour teaching you the language like https://tour.golang.org/.
- I think the home page should have how to install, and run a hello world command, like https://www.typescriptlang.org/. Issue Link
- I think the top navigation bar wraps poorly on mobile devices. I think it would be great to show an extra level of hierarchy, and moving to a side bar is probably necessary to fit in the hierarchy and show context. Issue Link.
- I think the docs page today is doing double duty catering to Graphviz core developers and Graphviz users. I think separating these audiences in the information hierarchy would allow better focus on pleasing both audiences.
- Right now it’s hosted off both graphviz.org and graphviz.gitlab.org (and the latter is canonical), I think we want it hosted on graphviz.org canonically in case we switch hosting providers. Issue Link
- I think the turquoise title banner is a bit tall, takes up a bit too much of the screen.
https://www.writethedocs.org/guide/writing/beginners-guide-to-docs/#what-to-write has a great set of things to put on your homepage, and then it gets further into information architecture too.
I think the current site has ‘good bones’ and we can incrementally make it better.
mattt, I’d absolutely love PRs to address the open issues on the doc tracker. I recently added a “Edit this page” button to the bottom of every doc page to make opening a merge request easier
Great work @mark. I love the consistent design that we are starting to get across the pages.
I’m a heavy user of the https://www.graphviz.org/doc/info/attrs.html page. I find it very useful to have everything on one page because then I can very quickly search for stuff with the built-in browser search. It would be great to have separate pages for each attribute as you propose, but I think this all-in page should remain as well. Although it looks much nicer now, it’s a pity that we now waste so much screen estate on the top bar. I tried to get used to it, but my (computer) screen always feels too small as it is and the top bar still keeps annoying me. One way to do it could be like https://material.io/.
One way to get interactivity could be to use something like http://magjac.com/graphviz-visual-editor/. Based on an idea that @scnorth gave me, I made a quick hack of the gallery which is available at http://magjac.com/graphviz/gallery/. Click on any graph to see what I mean.
We shouldn’t break the attrs page even if we add other content.
Node, Edge and Graph Attributes
- i consult this page frequently and like it as one page, but
- i would like to search by the “used by” column - only display node, edge, … attributes (hide the rest)
- it would also be nice to search the attributes by engine - only show neato attributes)
- some attributes (like nodesep) are applied at the graph level but affect a different object (nodesep affects nodes) there should be a way to associate these attributes with the affected object type
- some attributes need more explanation and/or visuals. Maybe expand/hide capability would work
- finally, there are 9 attributes that are marked “write only” … “not used or read by any of the layout programs”. This is inaccurate. Most or all are used by neato when the “-n” command line option is used. Some may also be used by other engines/situations
the “Documentation” page is too terse. Minimally the “Layout manual pages” and “Tool manual pages” sections need some explanatory (one-liner?) text.
Now, fumbling with Stephen’s bigger question - different users probably want different kinds of answers, so:
One way to categorize users might be:
- Brand new - what be this Graphviz thing and what might it do for me? Where do I start?
- A beginning user who may be getting frustrated. Yikes, too many attributes, all I want is a simple …
- An experienced user looking for a lightbulb moment/solution
Or, a way to categorize problems/issues might be:
- build/install issues, especially “not found”
- small to mid-sized graphs and the user wants more control over node/edge/cluster placement (i call these stylized issues)
- large-ish graphs and the user has macro issues with node/edge/cluster placement (did the printer explode?) or with performance (hours, really?)
- interactions with other packages - I’m a python/UML/networkx/Jupyter Notebook/… user and I need help (sometimes without reading any manual pages)
- I’m sure there are more
big +1 to a lot of these, particularly filtering by node/edge/graph/cluster. It presents a bit of a UX challenge to do the filtering and encourage users to interact with the filtering that way – it’s not enough to add the dropdown filters, you need to make it the most natural way to use the page.
Perhaps we could have a few indexes at the top (per-type). Perhaps there could be a edge-attrs.html page, and a node-attrs.page, keeping attrs.html as ‘all’.
I’ve just finished moving the generator for attrs.html from ksh to Python, so we should be empowered to make more featureful changes to the page now - doing things like filtering based off edge/node/graph was high up on the things I want to enable.
https://cloud.google.com/bigquery/docs/reference/standard-sql/functions-and-operators presents one way to organize a huge one-page documentation page: split pages per-topic, and a “one-page function reference” for those who want it all on one page. Every page having a table of contents sidebar.
I like that. It’s similar to what you get here at the forum through Discourse, e.g. here
The FAQ document needs work. It seems haphazard. The first thing we’re presented with is some esoteric information about Postscript fonts. In its time, it was OK as a repository of information we didn’t want to lose, but it could be a lot more helpful. Possibly this ties into the different audiences. Maybe FAQ itself is an obsolete concept. The audiences that come here looking for information probably include: end users (who are already invested in some platform, probably other than command line programming); developers (same), people trying to get some particular layout effect, and a very small audience maintaining or extending the code (which also divides into activities like porting, drivers, layout algorithms and satellite tools).
Theme-wise, today I found Docsy theme for technical docs. Here’s how a technical documentation site looks like with Docsy: https://www.docsy.dev/docs/, and another example: https://example.docsy.dev/docs/.
I came across it by looking incidentally at the Bazel docs, noting that they have a nice hierarchy and mobile-responsive page and a table of contents on the right, then I saw that they are also a Jekyll site and have adapted Docsy theme to run on Jekyll.
The table of contents on the right is particularly useful for long pages of options (like in attrs.html), check out how the bazel docs has a table of contents for a long page here: https://docs.bazel.build/versions/3.2.0/command-line-reference.html#fetch-options.
I’m interested to hear – does anyone have any doc sites they particularly like? Ones that we could draw inspiration from?
BTW I quite like the information architecture on the example Docsy site: https://example.docsy.dev/docs/
Here’s where your user finds out if your project is for them.
What does your user need to know to try your project?
See your project in action!
What does your user need to understand about your project in order to use it - or potentially contribute to it?
What can your user do with your project?
Show your user how to work through some end to end examples.
Low level refrence docs for your project.
How to contribute to the docs
Anyone wanting to put a live playground together - I have a bunch of components that can help (like a DOT editor and simple renderer): https://observablehq.com/@gordonsmith/graphviz-wasm-example
Which might be useful - especially if we pre-load it with a bunch of DOT related widgets (like the code colourizer / editor / d3-graphviz)?
This makes sense. Also integrate that nice tutorial from Adrian Ancona, already in jekyll.
I did a bit of research into how the most popular open source projects manage their documentation and wrote it up: https://www.markhansen.co.nz/popular-docs/
The short of it is, everyone’s using static site generators, and it doesn’t seem to matter much which one you use. Most sites scale down to mobile, and translations are handled differently all across the board.
Excellent article, very good analysis. Not sure what we should do differently - we used to have raw HTML though, and handmade HTML generators.
I agree. And you’re a very good writer too.