Documentation Diagram Design Guide

Design
1

Having diagrams that explain concepts visually is fundamental to good documentation. Unfortunately, most engineers are not designers, which means that most diagrams are more hindrance than help. Here are some examples of bad or mediocre technical diagrams:

Here are some examples of what I consider to be good diagrams:



What I’d like your help with:

Create a design language that fits with the Ember.js website design aesthetic for architectural and other explanatory diagrams. You should use the existing diagrams as a starting place. You can find them in the Ember.js website repository (just clone the repo to your computer and search for all of the images using something like Spotlight).

Once that’s done, we’ll create re-usable components (using something like SVG, perhaps) that contributors to the guides can use to build diagrams that are both consistent and pleasant to the eye.

9 Likes
2

Even if you’re not a designer, I’d really appreciate contributions of examples of great diagrams that we can use for inspiration.

3

Peepcode’s style of diagram has always looked nice to me. They use Helveticons.

4

Is there any diagram in particular that you’d like to see tackled?

5

I’m more interested in a common design language than improving a particular diagram.

6

My apologies. I wasn’t very clear there.

I fully understood your original request, I think. However, I was looking to see if there was a particular diagram that you thought might be a good one to look at as a sounding-board/prototype for exploring a design language that was liked by everyone. I have found in the past that creating a whole scheme for all diagrams in one go is very time consuming and ultimately nigh-on impossible when there are opinionated people to please. So, I wondered whether there was one diagram anyone interested could tackle to show ideas and possibilities. Once we nail one we can collectively move on to others and define the scheme iteratively.

I suspect most designers would prefer the tentative approach where they iterate with feedback

2 Likes
7

For those about to rock, a list of the current diagrams in the repo:

./source/guides/views/images/primitive-to-semantic-event.png
./source/guides/views/images/todo-list.png

./source/images/controller-guide/objects.png

./source/images/ember-data-guide/step1.png
./source/images/ember-data-guide/step10.png
./source/images/ember-data-guide/step11.png
./source/images/ember-data-guide/step12.png
./source/images/ember-data-guide/step13.png
./source/images/ember-data-guide/step14.png
./source/images/ember-data-guide/step2.png
./source/images/ember-data-guide/step3.png
./source/images/ember-data-guide/step4.png
./source/images/ember-data-guide/step5.png
./source/images/ember-data-guide/step6.png
./source/images/ember-data-guide/step7.png
./source/images/ember-data-guide/step8.png
./source/images/ember-data-guide/step9.png

./source/images/outlet-guide/application-choice.png
./source/images/outlet-guide/individual-post.png
./source/images/outlet-guide/list-of-posts.png

./source/images/routing-primer/app-without-root-route.png
./source/images/routing-primer/change-states-noroute-defined.png
./source/images/routing-primer/contexts-and-content.png
./source/images/routing-primer/data-loaded-shoes-route.png
./source/images/routing-primer/initial-load-router.png
./source/images/routing-primer/initial-view-wireup.png
./source/images/routing-primer/move-between-routes-transitionto-urlslug.png
./source/images/routing-primer/no-app-controller-defined.png
./source/images/routing-primer/shoe-route.png
./source/images/routing-primer/transition-to-in-router.png

./source/images/view-guide/container-view-shorthand.png
./source/images/view-guide/delegated.png
./source/images/view-guide/public-view-hierarchy.png
./source/images/view-guide/re-render.png
./source/images/view-guide/render-buffer.png
./source/images/view-guide/simple-view-hierarchy.png
./source/images/view-guide/template-appendChild-interaction.png
./source/images/view-guide/undelegated.png
./source/images/view-guide/view-hierarchy-ember.png
./source/images/view-guide/view-hierarchy-simple.png
./source/images/view-guide/view-lifecycle-ember.png
./source/images/view-guide/virtual-view-hierarchy.png
2 Likes
8

I ain’t no designer, mamma. But as a start, and because insomnia, I took this:

image

And made this:

Not as a specific improvement to one diagram, but to kick off discussion about how lifecycle diagrams might be represented.

The key things are:

  • Uses shades from the Ember website
  • Diagram name is embedded in the diagram, making it useful outside of the context of the website.
  • The version of Ember that the Diagram is correct for is also embedded.
  • Simple mono-chromatic iconography to highlight decision, looping and initiation.
  • No drop shadows
  • No gradients
7 Likes
9

I think the diagram @MrMcDowall showed above is a great starting point.

10

How about something like this?

(assuming I’ve got the actual flow correct).

11

Another attempt, slightly subtler…

Thoughts?

12

Another subtle iteration:

13

Two more iterations:

and

Interested in your thoughts.

(If anyone else would like a go I can export SVG elements and palates etc.)

3 Likes
14

Anyone for Lamprey?

4 Likes
15

I really like this design… The ones before looked a bit too overloaded with the check icons next to the arrows… Really nice.

16

As a Red/Green colorblind user, the colors are a bit too subdued, particularly the red arrow isn’t quite distinguishable from the green arrow – only the symbols are.

1 Like
17

Agree. That looks great. The red arrowed one is too colored for me. Not to mention the colorblind issue.

18

Replying for Christian (he wasn’t able to post images?)

"After a little design research and exploration, I came up with this look and feel. I ran with the idea of literal embers in a campfire (ember: “A small piece of burning or glowing coal or wood in a dying fire…” ). This made me think of old maps and the movie Moonrise Kingdom.

Thoughts on this direction?"

3 Likes
19

My trust level status is “visitor”, preventing me from posting images.

20

@cjeria I love those…really appreciate the thought you put into them, and I love that that lines aren’t just straight… I also love the legend in the bottom right corner. My only thought is that these might not fit in with the current design of the Ember.js website. Perhaps as you design them you could take a screenshot of the website and place it in the background and design over the top of it?