User Guide: The arrows in "img/commandLineTutorialTasks.png" are going in the wrong direction


(davidmichaelkarr) #1

In the User Guide, Figure 11.1, “Task dependencies”, looks like this:

The text associated with this image says “Both dist and test depend on the compile task.”. If that’s the case, the arrows are going in the wrong direction. It’s reasonable to assume that “A”==>“B” means that “A” depends on “B”, not the other way around.

I’m working on many miscellaneous text changes to the user guide, but I don’t have a good way to change these diagrams.


(davidmichaelkarr) #2

Never mind, I realized that the graphml files are the source for the pngs, and I found yEd. I also added a statement to the README.md that documents this relationship.


(Luke Daley) #3

I believe the idea here is that the arrows represent the data flow.

Regardless, I’d be inclined to ditch these graphs altogether.


(davidmichaelkarr) #4

I disagree on both points, for several reasons.

Concerning the direction of the arrow, I’m not going to argue whether the original concept was to represent data flow or not, I’m just going to point out why the original version isn’t useful.

We’re presenting a tutorial for new users of a tool. The illustration is intended to help them understand the relationship between these entities that they know little about, using mechanisms that they might be familiar with. Perhaps the most common graphical notation that someone might be familiar with is UML, which has a “depends” notation that consists of an arrow between two boxes, where the arrow represents the “depends” relationship. That is an exact fit for what we are trying to illustrate. It may be that under the covers, there is some sort of “data flow”, but I would say that would be much less visible to someone trying to learn this tool.

Concerning whether we need an image to convey this or not, outside of any technical arguments for what the image should look like, it’s valuable in a document like this to have more than just textual information. It’s hard for someone to slog through a large document that consists entirely of text. It’s a good idea to give them different ways to see the same information, if only to keep them awake.


(Luke Daley) #5

If the convention in UML is to have them the other way then I’m happy to flip them.

My objection to the images is that they will become out of date. Happy to keep them in if you think that’s best.


(davidmichaelkarr) #6

All documentation outside of code is at risk from obsolescence. We just have to be diligent if we want a quality product that will continue to drive new people to use this.

Fortunately, the graphml files are checked in next to each image (and I added a comment to the README.md about using “yEd” for generating pngs from graphml files). That at least makes it easy for someone to revise those images.