Add diagrams that explicitly demonstrate the structure and hierarchy of a signac project

[klywang]

The entry point to use signac can be steep for newcomers. It can be particularly difficult to understand how all of it's components fit together. To help new users develop intuition for siganc's structure, it may be beneficial to add diagrams which clearly show a project's structure.

Here is an example:

[vyasr]

Thanks for the idea! We can definitely try and add something like that to clarify the documentation.

[csadorf]

@klywang That's a great idea! Would you be interested in adding this yourself?

[klywang]

Yeah! What software do you guys typically use to make your diagrams?

[csadorf]

@klywang Awesome! I've used lucidchart in the past for these purposes, but any applications that allows you to create vector graphics should suffice (such as Adobe Illustrator). Just make sure to store it in an open format so that we can potentially edit it later again and it should be fine.

[klywang]

I started making a flow chart but it ended up being pretty large and hard to look at.
I've drafted up a more inforgraphic-style diagram instead. I can use Adobe Illustrator to make graphics and layouts for it. Let me know what you guys think.

[vyasr]

I love it, but I think the trick will be hitting the right level of detail for it to be informative without being too overwhelming. For example, I think another graphic clarifying that the statepoint, data, and document are files in the job would be helpful. I do like the infographic style, it's a nice changeup from straight UML-type diagrams (which you could still do for the flowchart).

[klywang]

So have the folder heiarchy as a seperate diagram from the contents of the folders?
Would this mean there would be diagrams for the following:
(1) An overview of the file structure. Focuses on defining basic concepts like "project", "workspace", "job", and "statepoint" and how they interact with siganc/signac-flow
(2) A job-centric graphic that shows how data is stored within a folder
(3) A UML diagram or graphic to illustrates how components of signac-flow are used to construct a workflow

If it's broken up like this, I can format them so they fit nicely on slides (if you guys are interested)

[csadorf]

@klywang I think your proposed division makes sense.

[vyasr]

@klywang are you still interested in this? We're chatting about docs again and would love to move forward with getting this type of mind map into our docs.

[klywang]

The most recent diagram I made looks like this, but I'm not 100% sure what other information we would want on it.

[cbkerr]

Resolving this as the diagrams are on the new concepts page! https://docs.signac.io/en/latest/intro.html