Your IAM repository should explain the problem and result before asking anyone to read installation commands.
Make the first screen useful to someone who didn't build the lab. A tool list and twenty screenshots won't tell that reader why the project matters or what you personally demonstrated.
Keep the technical detail, but give it a clear structure: a short business problem, an evidence-backed result, and a route into the configuration and reasoning. That helps both a quick reader and someone who wants to investigate further.
Put the business problem above the setup instructions
Start with a plain sentence such as: “This lab tests whether a transferred employee loses access to the old team's files while keeping the access required for the new job.”
That sentence establishes the user, the change, and the expected result. A reader can understand it without recognizing every product in your diagram.
Then explain the scope: fictional users, an isolated environment, and a deliberately small set of resources.
A project description should not force the reader to infer the objective from the names of your virtual machines.
Put the tested result near the top of the page
The first screen should answer three questions:
| Question | What to show |
|---|---|
| What did you test? | The user action and access requirement |
| What happened? | The observed outcome under stated conditions |
| Where is the evidence? | A labeled result table, screenshot, or relevant log |
For example: “The transferred user received the new team membership. The old permission was removed, and a fresh access test confirmed the old resource was unavailable.”
Use that wording only when your actual tests support it. If you modeled part of the process instead of implementing it, say which part.
One labeled result is easier to evaluate than an unexplained gallery. The caption should state what the evidence establishes and avoid suggesting it proves more than you tested.
Let a technical reader inspect the reasoning
Below the summary, describe the architecture, the key configuration, and the test conditions.
Explain why you chose the permission model and how you checked for unintended access. Mention the relevant session or identity context rather than assuming every screenshot was taken under the same conditions.
Include a troubleshooting note when it teaches something specific. “I corrected a group assignment after the denial test unexpectedly succeeded” gives the reader a reason to inspect your analysis.
For the structure of that deeper section, use a README layout that separates the problem, configuration, and evidence.
Keep reference material out of the main narrative
Long command output, repeated screenshots, and detailed setup notes can live in separate files or clearly labeled sections.
They are useful when someone wants to reproduce the work. They are not always useful in the first minute of evaluation.
Use descriptive link labels. “Test results and limitations” tells a reader what they will find. “More” does not.
This structure also helps you. You can update a configuration detail without rewriting the short explanation of the problem the project addresses.
Test the page with someone who did not build it
Ask a friend or colleague to look at the project briefly, then explain what it demonstrates.
Do not rescue the page with a spoken explanation. Their uncertainty shows you what the page has not yet communicated.
If they can name the tools but not the result, move the result higher. If they think a lab was a production deployment, correct the labeling. If they cannot tell which parts you built, make your contribution explicit.
The portfolio guidance in The Six-Figure IAM Career Playbook is meant to connect practical work with a credible career move. The $9 book includes three project areas so you have something useful to explain, not just a prettier repository.
A portfolio should reduce the effort required to understand your skills. Start by making one project easier to read before adding another.