New Concepts Page

[bdice]

Issue Description

During office hours, @atravitz led a discussion of what a revised Concepts page might look like. I took notes, copied below. I have rephrased the notes from our original collaborative document, to make action items and next steps more clear. Please comment below if you are interested in helping!

We should convert the SIAM 2019 graphic (below) into a home page figure for conveying core concepts. Caption should link to Concepts page.

The new Concepts page contents should be an increasingly complex diagram, built step by step with alternating images/descriptions. Key words are defined, bolded, and linked to topic guides. Very small code snippets, with links to more involved code snippets. The concepts page should feel a bit like a glossary that follows the stages / life cycle of a project. The Concepts page should convey aim/purpose of the framework, establish a mental model, and introduce core terminology.

Initial content draft:

• Introduce idea of a signac data space (Project). It looks like a workspace/ and signac.rc.
• Describe state point -> uniquely identifies a Job. The "dot" is a Job, it is described by a state point and labeled with an id. It exists in the Project.
• You can initialize jobs with init.py (3-4 lines of code)
• Introduce flow. At the lab bench, you've decided what experiments to run, now to run the experiments (maybe another analogy is needed).
• Introduce other half of the top SIAM 2019 figure. We need better verbs than "Generate, Process, Analyze" (originally intended for a specific simulation workflow)
• signac-flow executes workflow in an order defined by conditions. Link to docs here. The Defining a Workflow guide page is not great and could be separately improved.
• Analysis is done via user code. Show simple example.

Proposed change (optional)

We plan to do work on this during office hours.

Additional context (optional)

Airflow's concepts page has very nice design and a ton of info: https://airflow.apache.org/docs/apache-airflow/stable/concepts.html

Closely related to #82, #45.

[atravitz]

@klywang we'd love to have you join for this week's office hours (Thursday at noon) to incorporate some of the related work you've done on this!

[atravitz]

Here's the google doc where we're keeping all our ideas for this:
https://docs.google.com/document/u/1/d/1_merhcK3ohas4IloE616yL7gypMRFcaQLh2oChExC7o/edit?pli=1

[cbkerr]

Congrats everyone who helped wrap up this longstanding issue!