en/level-3-release-manager/3-9-generate-the-project-documentation/

[giscus[bot]]

en/level-3-release-manager/3-9-generate-the-project-documentation/

Generate readable documentation of an undocumented Salesforce org with sfdx-hardis: objects, flows, Apex and permissions, from the sources in Git.

https://sfdx-hardis-training.cloudity.com/en/level-3-release-manager/3-9-generate-the-project-documentation/

[oleg-mastriukov]

Open the page for Installation_Assign_Crew

It would be nice to explain how to view the .md files as pages in vscode

[nvuillam]

Agreed, the lab said "open the page" and never said how. Step 3 now does: Ctrl+Shift+V, or right-click the tab of the file and Open Preview.

[arkonautom]

a) Should I ignore this failing action? Command as a whole was ok.

b) Step 1 image has 1 2 3 but all are described in text as a b c under 2.
c) On switching to markdown preview mermaid charts would blink with content before going blank. I had "Markdown Preview Mermaid Support" extension installed (remnant of historical setup most likely) that has note "[!WARNING] This extension is deprecated as it has been merged into VS Code 1.121.", After uninstalling it and restarting extensions (+ reopening MD files) diagrams showed up ok. Also "(View History)" started to work.
d) Step 5.1. It would be good to point an exact suggested place to put paragraph in (e.g. before or right after Installation__c header) to facilitate a default habbit. Following points have text to expand, this does not.
e) Step 5.2. What was schedule "preparation buffer" about, is this about Lab 2.5 where we copy-pasted apex?
f) Step 5.3. Safety point appear to be already covered "A crew larger than the installation cap is brought back down to the cap: too many people on a small roof is a safety problem."
g) Does it mean that "DO_NOT_OVERWRITE_DOC=TRUE" page will go stale as a whole when changes occur? E.g. Step 7 elaborates that "Documentation generated once is out of date in a month." and implies that changes should be done to artifacts generated via monitoring repo instead? Looking for a suggested / sanctioned approach here.

[nvuillam]

Thanks for this one, several points led to changes.

a) Yes, ignore it. Before it starts, the command looks for an optional second org named TECHNICAL_ORG, which some projects use to call Agentforce. You have none, so sf org display fails, and the panel shows the red cross even though the command does not need it. Every learner gets that noise, so the next version of sfdx-hardis stops looking when no such org is declared: hardisgroupcom/sfdx-hardis#2437.

b) The pills are in the text too: each part in step 2 ends with (1), (2) or (3). The site letters the sub-list a, b, c on its own, which is what you saw.

c) Good find. Recent VS Code shows Mermaid in its own preview, and the old extension fights it. Uninstalling it was the right call.

d) Right under the title of the page, before the first generated section. That is also where the AI description lands on a project that has one.

e) and f) You're right on both, and the lab was wrong. The buffer is PREPARATION_DAYS in InstallationScheduler.cls (Lab 2.5 only tested it), and its ApexDoc already says why: the warehouse needs time to prepare the pallets. The safety reason is already in the description of Installation_Assign_Crew and of the crew capacity cap field. Step 5 now keeps the one paragraph only a person can write, on the Installation page, and has you find the other two reasons in the generated pages: a reason written in the metadata itself reaches the documentation on every run. It is on the site now: #354.

g) Yes, a TRUE page is frozen as a whole: a field added next month will not show on it. That is why it suits pages written mostly by a person. The Complete the generated documentation page lists three ways:

• Protect a whole page, as in the lab.
• Override only the AI-written part through its cache file, so the rest of the page keeps being regenerated.
• Write your own pages under docs/, which the generator never touches.

The approach that ages best is the one e) and f) show: write the reason in the description of the object, field or flow, or in the ApexDoc, and every generation carries it, including the nightly one of the monitoring repository.