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.
1 Like
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 graphviz / graphviz.gitlab.io Ā· GitLab. 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 Go Playground - The Go Programming Language, 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.
A beginnerās guide to writing documentation ā Write the Docs 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.
1 Like
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 
1 Like
Great work @mark. I love the consistent design that we are starting to get across the pages.
Iām a heavy user of the Attributes | Graphviz 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 Graphviz Visual Editor. Based on an idea that @scnorth gave me, I made a quick hack of the gallery which is available at Gallery. Click on any graph to see what I mean.
We shouldnāt break the attrs page even if we add other content.
my issues
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
1 Like
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.
1 Like
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.
1 Like
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).
1 Like
Theme-wise, today I found Docsy theme for technical docs. Hereās how a technical documentation site looks like with Docsy: Welcome to Docsy | Docsy, and another example: Documentation | Goldydocs.
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: Command-Line Reference - Bazel 3.2.0.
Iām interested to hear ā does anyone have any doc sites they particularly like? Ones that we could draw inspiration from?
1 Like
BTW I quite like the information architecture on the example Docsy site: Documentation | Goldydocs
Overview
Hereās where your user finds out if your project is for them.
Getting Started
What does your user need to know to try your project?
Examples
See your project in action!
Concepts
What does your user need to understand about your project in order to use it - or potentially contribute to it?
Core Tasks
What can your user do with your project?
Tutorials
Show your user how to work through some end to end examples.
Reference
Low level refrence docs for your project.
Contribution Guidelines
How to contribute to the docs
1 Like
Anyone wanting to put a live playground together - I have a bunch of components that can help (like a DOT editor and simple renderer): GraphViz WASM Example / Gordon Smith | Observable
Also for ālive documentationā I have a Markdown editor which supports āliveā embedded JavaScript using the ObservableHQ runtime engine: Storyboard
Which might be useful - especially if we pre-load it with a bunch of DOT related widgets (like the code colourizer / editor / d3-graphviz)?
1 Like
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: How are popular open source projects documented?
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.
1 Like
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.