An IAM README should answer what problem you modeled, what you built, how you tested it, and what the result proves before someone opens the configuration files.
A long installation diary can contain every detail while hiding those answers.
Use a consistent structure to make the work easy to inspect. Keep the evidence specific to each project so the portfolio doesn't become the same setup story repeated under different titles.
Start with the requirement and result
Open with a short statement of the fictional business problem.
For example: “Research users need read-only access to sample reports; unrelated users should be excluded. The lab verified the intended read access and two expected denials.”
Label the environment as a lab immediately. This gives a skimming reader the purpose and outcome without requiring them to understand every tool first. It also forces you to decide what the project is actually claiming to demonstrate.
Show the design with one understandable diagram
Identify the components and relationships relevant to the requirement.
For a directory project, that may be users, groups, and a resource. For SSO, it may be the user, application, identity provider, and the relevant exchanges. Avoid adding decorative systems that do not affect the tested behavior.
Explain the important boundary below the diagram. A reader should know which component makes which decision and which parts you implemented. Mark external services, assumptions, and untested areas clearly rather than letting the diagram imply a larger deployment.
Summarize the configuration, then link to detail
Describe the settings that determine the result. Keep the main page readable. Put lengthy setup notes or sanitized examples in separate sections or files when necessary. Do not publish credentials, tokens, personal data, or confidential organizational information.
GitHub's README guidance explains the README's role as an introduction to the project.
Treat that introduction as a guided explanation, not a place to paste every command you ran in chronological order.
Make the test table the center of the evidence
For each test, record the identity, action, expected outcome, observed outcome, and evidence location.
Include an intended success and a relevant denial or failure case. If the project models a lifecycle change, include the before and after states.
Explain any result that differed from the expectation.
This is where the README moves from describing configuration to demonstrating behavior. A screenshot should support a particular test or setting, not appear as an unexplained image that the reader must interpret alone.
Include troubleshooting and limits without inventing drama
Describe one meaningful problem you actually encountered or deliberately introduced in the isolated lab.
State the observation, the evidence that guided the next check, the correction, and the retest. If the project worked without a noteworthy incident, don't manufacture a story.
Then identify the limits: scale, untested scenarios, session assumptions, or features you researched but did not implement.
Use honest troubleshooting notes to keep this section useful. Credibility comes from accurate reasoning, not from making every project sound like an emergency.
Use five sections to check that the project is explainable
Before publishing, check this outline:
| Section | Question it should answer |
|---|---|
| Problem and result | What should happen, and what did you verify? |
| Design and configuration | Which components and settings matter? |
| Tests and evidence | What was expected and what was observed? |
| Troubleshooting and limits | What did you learn, and what remains outside the claim? |
| Reproduction and safety | What can another person understand or repeat safely? |
Keep the structure consistent while changing the substantive evidence for each project.
The Six-Figure IAM Career Playbook includes three IAM lab directions and guidance on using the evidence in a career move. The $9 guide helps connect the project to a role before you start writing its README.
Make the route from problem to evidence obvious.