Fill introduction of the documentation

[pkausw]

This PR implements a little more introductory text before the step-by-step setup instructions that @aalvesan implemented some time ago. Additionally, it includes a proposed outline for later chapters - I'm happy to discuss this of course!

[mschrode]

Hi @pkausw , reads very nice! I spotted a few typos and have a few wording suggestions, please see below. (Let me know if you prefer I modify the files myself):

General: suggest to follow CMS style guidelines

• particle names non-italic
• "fig" --> "Fig."
• "Run2" --> "Run 2"

i)

• add the QU logo? and the FSP-CMS one

ii)

• consistent capitalisation of the sections. Suggest CMS style convention: main sections all capitalised (OK!) and subsections only the first word. Then:
  • 1.1 structure
  • 1.3 setup
  • 2.1 mother
  • 2.4: producer is also a class, no? Then Producer
  • 3.1 categories
• should class names (and ColumnFlow?) be spelled in texttt or similar (or with the grey box as later in the document)? Then in 1, all subchapters of 2.4

v)

• Run 2

Do we need the list of figures and list of tables? Remove at least the empty list of tables

• "ColumnFlow is a back-end..."
• "well-received"? --> "common in the HEP community and well-maintained"
• developers
• "However, ColumnFlow is designed in an experiment- agnostic way..."
• "visit the documentation"
• "questions and comments"
• "defines the work packages"
• "law tasks" --> would set it as \texttt{law} or \textsc{law} so that it is immediately clear this is a program

caption Fig. 1.1

• "general work packages in a data analysis"
• "line widths"?
• More information is provided in Ref. [1]"
• say here what the different line styles mean. Or is this in Ref. [1]? Then: "The meaning of the line styles is explained in Ref. [1]" instead of the last sentence

• "The second block in Fig. 1.1"
• set "parquet" in texttt or capitalised as ROOT?
• "final quantities" --> "final observables"
• add reference to combine paper
• "This structure allows a full end-to-end analysis"
• "luigi and law" --> program names
• "sustainable and reproducible workflow" --> "automatically organised and reproducible workflow"
• reference to H->4l paper

caption Fig. 1.2

• "full Run 2 dataset"
• non-italic particle names
• "Ref."

• standard model (non capitalised)
• "golden channel to discover the Higgs boson" or "to measure the properties of the Higgs boson" (not rediscovered)
• I would invert the order of the itemize list
• "it is a fully resolved final state – the Higgs boson can be reconstructed from the reconstructed particles"
• "excellent mass resolution due to the high lepton-pt resolution"

• does CF also run on MacOS?
• consistent capitalisation of URL

• "you can keep the default name" --> "you can keep the default value"

• the middle paragraph on law tasks: would put the sentences "By default, ... file accordingly" at the end, since it is an optional modification. Maybe say explicitly which config variable one should change

• "candidates, we will"
• "will first need to reconstruct the four leptons in the final state. We will do this by writing a Selector" sounds a bit strange: the selector would select sth, while I want to reconstruct sth. Maybe like "To select the four lepton candidates, we will write a Selector"

[aalvesan]

@matsch I implemented most of these fixes :)

[mschrode]

Hi @aalvesan , you have the permissions to commit now, no? I saw you appended a new commit

[pkausw]

Thanks for implementing these changes @aalvesan ! I'll go ahead and merge this, thanks for the review @mschrode !