Skip to content

Commit a8880ca

Browse files
timurbazhirovtimurbazhirov
authored
Merge pull request #376 from Exabyte-io/improvement/review-session
improvement: tutorials via iterative agentic reviews
2 parents 7ba2b61 + 2b2358b commit a8880ca

84 files changed

Lines changed: 2473 additions & 2481 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎AGENTS.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,8 @@
33
Guidance for AI coding agents working in the Mat3ra documentation
44
repository. Read this alongside [`WRITING-STYLE.md`](WRITING-STYLE.md)
55
and [`README.md`](README.md), which remain the canonical references for
6-
prose style and formatting respectively.
6+
prose style and formatting respectively. For running structured quality
7+
reviews, see [`REVIEW.md`](REVIEW.md).
78

89
## Repository at a Glance
910

‎REVIEW.md‎

Lines changed: 271 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,271 @@
1+
# Documentation Review Guide
2+
3+
This file defines a repeatable review process for evaluating and improving
4+
the Mat3ra documentation. It is designed for AI coding agents but can also
5+
be used by human reviewers.
6+
7+
Read [`WRITING-STYLE.md`](WRITING-STYLE.md) and [`AGENTS.md`](AGENTS.md)
8+
first — they are the canonical references for prose style and agent
9+
guidance respectively. This file builds on them.
10+
11+
---
12+
13+
## Review Panel
14+
15+
The review simulates a panel of three personas. Each brings a different
16+
lens to the documentation:
17+
18+
| ID | Persona | Focus |
19+
|----|---------|-------|
20+
| R1 | Experienced computational materials scientist (5–10 yr) | Technical accuracy, depth, correctness of methods and parameters |
21+
| R2 | First-year postdoc in comp chem / AI for materials | Cross-linking, discoverability, ML workflow clarity |
22+
| R3 | Last-year PhD student in comp. mat. sci. | Clarity for newcomers, step-by-step completeness, visual aids |
23+
24+
When scoring, consider how each persona would rate the page independently,
25+
then average.
26+
27+
---
28+
29+
## Evaluation Criteria
30+
31+
Score each page on a 0–10 scale across five criteria:
32+
33+
### C1: Structural Consistency
34+
35+
| Score | Description |
36+
|-------|-------------|
37+
| 9–10 | Numbered sections (`## 1.`, `### 1.1.`), imperative subheadings, no list directly under heading, proper H1/H2/H3 hierarchy |
38+
| 7–8 | Numbered sections but inconsistent subheading style, or one heading-level violation |
39+
| 5–6 | Unnumbered sections, gerund subheadings, lists under headings |
40+
| 0–4 | No structure, flat document, missing H1 |
41+
42+
### C2: Voice & Style
43+
44+
| Score | Description |
45+
|-------|-------------|
46+
| 9–10 | Third-person/passive throughout, no forbidden words, no "you/your/we/our", acronyms introduced on first use |
47+
| 7–8 | 1–2 isolated voice violations, otherwise clean |
48+
| 5–6 | Frequent "we"/"you" usage, some forbidden words |
49+
| 0–4 | Pervasive second-person, marketing tone |
50+
51+
**Forbidden words** (from `WRITING-STYLE.md`): *Simply, Clearly,
52+
Obviously, In fact, Furthermore, Moreover, Complete, In particular,
53+
Really, Distinct, Various, Automatically, Finally*.
54+
55+
### C3: Technical Depth
56+
57+
| Score | Description |
58+
|-------|-------------|
59+
| 9–10 | Method explained with references, key parameters documented, expected results stated, comparison to experiment/literature where applicable |
60+
| 7–8 | Method referenced but not explained, parameters listed without rationale |
61+
| 5–6 | Procedural steps only, no "why" |
62+
| 0–4 | Incomplete procedure, missing steps |
63+
64+
### C4: Navigability & Cross-Linking
65+
66+
| Score | Description |
67+
|-------|-------------|
68+
| 9–10 | All related tutorials cross-linked, prerequisite tutorials referenced, same-site relative links, cross-site macro links |
69+
| 7–8 | Most links present, one or two missing cross-references |
70+
| 5–6 | Minimal linking, isolated page |
71+
| 0–4 | Broken links or no links at all |
72+
73+
### C5: Media & Visuals
74+
75+
| Score | Description |
76+
|-------|-------------|
77+
| 9–10 | All images have alt text + title, `.webp` format, video embeds present, screenshots current |
78+
| 7–8 | Images present with alt text but PNG format, or one missing caption |
79+
| 5–6 | Some images without alt/title, outdated screenshots |
80+
| 0–4 | No images or broken image links |
81+
82+
---
83+
84+
## How to Run a Review
85+
86+
### Quick Prompt (paste into chat)
87+
88+
```
89+
Review the documentation under `lang/en/docs/tutorials/` following the
90+
process defined in REVIEW.md. Score each page on the 5 criteria (C1–C5),
91+
produce a scorecard table, then refactor the lowest-scoring pages to bring
92+
the average above 9/10. Work in rounds of 5–8 files, updating the
93+
scorecard after each round.
94+
```
95+
96+
### Full Prompt (for thorough multi-round review)
97+
98+
```
99+
You are a review panel consisting of:
100+
101+
(1) An experienced computational materials scientist with 5–10 years of
102+
experience
103+
(2) A first-year postdoc in comp chem / AI for materials
104+
(3) A last-year PhD student in comp. mat. sci.
105+
106+
Read REVIEW.md, WRITING-STYLE.md, and AGENTS.md. Then:
107+
108+
1. Score every tutorial page under `lang/en/docs/tutorials/` on the 5
109+
criteria defined in REVIEW.md (C1–C5, 0–10 scale).
110+
2. Produce a scorecard table grouped by section.
111+
3. Identify the lowest-scoring pages and refactor them in rounds of 5–8
112+
files per round.
113+
4. After each round, re-score the refactored pages and update the
114+
scorecard.
115+
5. Continue until the mean score across all pages is ≥ 9/10.
116+
6. Produce a final scorecard and a walkthrough of all changes made.
117+
```
118+
119+
### Scoping a Partial Review
120+
121+
To review a specific section only:
122+
123+
```
124+
Review only the files under `lang/en/docs/tutorials/dft/vibrational/`
125+
following REVIEW.md. Score, refactor, and re-score.
126+
```
127+
128+
---
129+
130+
## Style Checklist (Quick Reference)
131+
132+
This distills the most common issues found during reviews. Check every
133+
page against this list:
134+
135+
- [ ] One H1 (`#`) on line 1; sub-headers use sentence case
136+
- [ ] Sections numbered: `## 1.`, `### 1.1.`
137+
- [ ] Subheadings are imperative ("Import the workflow", not "Importing
138+
the workflow")
139+
- [ ] No list starts directly under a heading — open with prose first
140+
- [ ] Lists are flat (single level); images/code blocks are flush-left
141+
- [ ] Third person / passive voice throughout; no "you", "your", "we",
142+
"our"
143+
- [ ] None of the forbidden words from `WRITING-STYLE.md`
144+
- [ ] No acronyms in headings; acronyms introduced on first use in body
145+
- [ ] Same-site links use relative paths
146+
- [ ] Cross-site links use `{{ guide_url }}`, `{{ reference_url }}`, or
147+
`{{ dev_url }}` macros
148+
- [ ] All images have alt text and title: `![alt](path "title")`
149+
- [ ] Prefer `.webp` images; each file < 1 MB
150+
- [ ] Video embeds use the standard `<div class="video-wrapper">` pattern
151+
- [ ] Version notes include "and later" (e.g., "5.2.1, 5.4.0, 6.0.0,
152+
6.3, and later")
153+
- [ ] `mkdocs.yml` updated if pages were added, renamed, or moved
154+
155+
---
156+
157+
## Baseline Scores (June 2025)
158+
159+
These scores reflect the state after 12 rounds of review. Use them as a
160+
starting point — re-score before making changes to account for any
161+
subsequent edits.
162+
163+
| Section | Pages | Mean Score | Status |
164+
|---------|-------|------------|--------|
165+
| DFT Electronic | 16 | 9.2 | ✅ Refactored |
166+
| DFT Vibrational | 4 | 9.0 | ✅ Refactored |
167+
| DFT Thermodynamic | 1 | 9.2 | ✅ Refactored |
168+
| DFT Chemical | 2 | 9.2 | ✅ Refactored |
169+
| DFT Optical | 1 | 9.2 | ✅ Refactored |
170+
| DFT Addons | 2 | 9.2 | ✅ Refactored |
171+
| Python ML | 5 | 9.1 | ✅ Refactored |
172+
| ML (legacy + DeePMD) | 4 | 9.0 | ✅ Refactored |
173+
| Reference / Overview | 4 | 8.4 | ✅ Refactored |
174+
| **Tutorials overall** | **39** | **9.1** | |
175+
| Templating | 2 | ~6.0 | ⬜ Not yet reviewed |
176+
| General Functionality | 2 | ~5.5 | ⬜ Not yet reviewed |
177+
| Materials | ~12 | ~6.5 | ⬜ Not yet reviewed |
178+
| Materials (specific) | ~20 | ~6.0 | ⬜ Not yet reviewed |
179+
180+
---
181+
182+
## Common Refactoring Patterns
183+
184+
These patterns were applied repeatedly during the 12-round review.
185+
Future agents should follow the same approach:
186+
187+
### Voice Fixes
188+
189+
```diff
190+
-We will now calculate the band structure.
191+
+The band structure is calculated as follows.
192+
193+
-In this tutorial, we demonstrate how to...
194+
+This tutorial demonstrates how to...
195+
196+
-You should click the button.
197+
+Click the button. / The button should be clicked.
198+
199+
-our platform
200+
+the platform
201+
```
202+
203+
### Section Numbering
204+
205+
```diff
206+
-## Create Job
207+
+## 1. Create the job
208+
209+
-## Choose Workflow
210+
+## 2. Select the workflow
211+
212+
-### Examine Input Files
213+
+### 2.1. Examine the input files
214+
```
215+
216+
### Heading Style
217+
218+
```diff
219+
-### 1.1. Importing a workflow
220+
+### 1.1. Import a workflow
221+
222+
-### 4.2. Example Results
223+
+### 4.2. Example results
224+
```
225+
226+
### No List Under Heading
227+
228+
```diff
229+
### 1.1. Import a bank workflow
230+
231+
- - Navigate to the Workflows Bank page.
232+
- - Search for the workflow.
233+
+First, navigate to the Workflows Bank page.
234+
+Then, search for the workflow.
235+
```
236+
237+
### Version Notes
238+
239+
```diff
240+
- The present tutorial is written for Quantum ESPRESSO at versions
241+
- 5.2.1, 5.4.0, 6.0.0 or 6.3.
242+
+ This tutorial applies to Quantum ESPRESSO versions 5.2.1, 5.4.0,
243+
+ 6.0.0, 6.3, and later.
244+
```
245+
246+
### Verbose Workflow Details → Collapsible
247+
248+
When a tutorial has extensive workflow/parameter documentation that
249+
interrupts the procedural flow, move it into a collapsible block:
250+
251+
```markdown
252+
<details markdown="1">
253+
<summary>Expand to view input parameter details</summary>
254+
255+
... detailed parameter documentation ...
256+
257+
</details>
258+
```
259+
260+
---
261+
262+
## Extending This Guide
263+
264+
When adding new evaluation criteria or refactoring patterns:
265+
266+
1. Add the criterion to the "Evaluation Criteria" section with score
267+
descriptions.
268+
2. Add a corresponding checklist item to "Style Checklist".
269+
3. If a new refactoring pattern emerges, add a diff example to "Common
270+
Refactoring Patterns".
271+
4. Update the baseline scores table after each review cycle.

‎lang/en/docs/models-directory/dft/overview.md‎

Lines changed: 36 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,54 @@
11
# Density Functional Theory Model
22

3-
We introduce here the theoretical framework of **Density Functional Theory (DFT)**.
3+
**Density Functional Theory (DFT)** is a quantum mechanical modeling method used to investigate the electronic structure of many-body systems, primarily atoms, molecules, and condensed matter. DFT reformulates the many-electron Schrödinger equation in terms of the electron density rather than the many-body wave function, reducing the problem from 3N to 3 spatial variables [^1].
4+
5+
## Theoretical Foundations
6+
7+
The method rests on two theorems by Hohenberg and Kohn [^2]:
8+
9+
1. The ground-state energy of a many-electron system is a unique functional of the electron density.
10+
2. The electron density that minimizes the energy functional is the exact ground-state density.
11+
12+
In practice, the Kohn–Sham formulation [^3] maps the interacting many-electron system onto a set of non-interacting single-particle equations with an effective potential, making the problem computationally tractable.
13+
14+
### Exchange-Correlation Functionals
15+
16+
The exchange-correlation (XC) functional captures the quantum mechanical effects of electron exchange and correlation. Common approximations include:
17+
18+
- **Local Density Approximation (LDA)** — depends only on the local electron density; tends to overbind.
19+
- **Generalized Gradient Approximation (GGA)** — includes density gradients; the PBE functional [^4] is the most widely used. GGA is the default on the Mat3ra platform.
20+
- **Hybrid Functionals** — mix a fraction of exact (Hartree–Fock) exchange with GGA; HSE06 [^5] is supported for more accurate band gaps. See the [HSE tutorials]({{ guide_url }}/tutorials/dft/electronic/hse-vasp-bg/).
21+
- **GW Approximation** — a many-body perturbation theory approach for quasiparticle energies; supported through [VASP]({{ reference_url }}/software-directory/modeling/vasp/overview/) and [Quantum ESPRESSO]({{ reference_url }}/software-directory/modeling/quantum-espresso/overview/). See the [GW tutorial]({{ guide_url }}/tutorials/dft/electronic/gw-vasp-bg/).
22+
23+
!!!info "Known limitation: band gap underestimation"
24+
Standard GGA-DFT systematically underestimates electronic band gaps due to the self-interaction error and the derivative discontinuity of the XC functional. Hybrid functionals and the GW approximation provide improved accuracy at higher computational cost.
25+
426

527
## [Parameters](parameters.md)
628

7-
The list of parameters affecting DFT is presented [in this page](parameters.md).
29+
The list of parameters affecting DFT calculations is presented [in this page](parameters.md), including the choice of XC functional, plane-wave cutoff energy, and k-point sampling.
830

931
## [Accuracy](accuracy.md)
1032

11-
We discuss the factors limiting the [accuracy](../../models/accuracy.md) of DFT [here](accuracy.md).
33+
Factors limiting the [accuracy](../../models/accuracy.md) of DFT are discussed [here](accuracy.md), covering basis-set convergence, pseudopotential quality, and XC functional limitations.
1234

1335
## [References](references.md)
1436

15-
A comprehensive list of references reviewing the theoretical background underlying DFT is outlined [in this page](references.md), to be referred to at the reader's discretion.
37+
A comprehensive list of references reviewing the theoretical background underlying DFT is outlined [in this page](references.md).
1638

1739
## [Structured Representation]({{ data_url }}/models-directory/dft/data/)
1840

1941
[This page]({{ data_url }}/models-directory/dft/data/) contains an example [structured representation]({{ data_url }}/data-structured/overview/) for the DFT model.
2042

2143
## [Special Notes](notes.md)
2244

23-
We have collected [in this page](notes.md) some special notes on special precautions that need to be taken when considering the different [parameters](parameters.md) of DFT.
45+
Special precautions that need to be taken when considering the different [parameters](parameters.md) of DFT are collected [in this page](notes.md).
46+
47+
48+
## Links
49+
50+
[^1]: [Wikipedia Density Functional Theory](https://en.wikipedia.org/wiki/Density_functional_theory)
51+
[^2]: P. Hohenberg and W. Kohn, "Inhomogeneous Electron Gas," Phys. Rev. 136, B864 (1964). [DOI](https://doi.org/10.1103/PhysRev.136.B864)
52+
[^3]: W. Kohn and L. J. Sham, "Self-Consistent Equations Including Exchange and Correlation Effects," Phys. Rev. 140, A1133 (1965). [DOI](https://doi.org/10.1103/PhysRev.140.A1133)
53+
[^4]: J. P. Perdew, K. Burke, and M. Ernzerhof, "Generalized Gradient Approximation Made Simple," Phys. Rev. Lett. 77, 3865 (1996). [DOI](https://doi.org/10.1103/PhysRevLett.77.3865)
54+
[^5]: J. Heyd, G. E. Scuseria, and M. Ernzerhof, "Hybrid functionals based on a screened Coulomb potential," J. Chem. Phys. 118, 8207 (2003). [DOI](https://doi.org/10.1063/1.1564060)

0 commit comments

Comments
 (0)