iOi · How these guides are made

1 The system

SharePoint won’t render HTML in the browser (it serves it as a download), so we don’t rely on it to host a website. Instead each tool does what it’s good at:

Layer	Role	Lives in
Monday.com board	The hub everyone already checks — one row per tool, linking the PDF	Monday.com
PDFs	The “read it now” copies — render inline in SharePoint, zero friction	SharePoint
HTML pack (this folder)	The real navigable site, the source of truth, and the kit for making more guides	SharePoint (download & open)

Source of truth: the HTML is the master. The PDFs are generated from it. Always edit the HTML, then regenerate the PDFs — never edit a PDF directly, or the two will drift.

2 How to read the guides

Most people: open the Monday.com board and click a tool — its PDF opens straight in the browser.

The full HTML experience: in SharePoint, download this whole folder (select it → Download — SharePoint zips it), unzip, and double-click index.html. The landing page and every guide link work offline. Opening a single .html straight from SharePoint will not work — it has to be downloaded as a folder first.

3 How a guide is built

Two stages: write the content, then publish it.

Stage 1 — Write the content (.docx)

The content for each guide is produced in a Claude chat session using the prompt at Guides/iOi-guide-rewrite-prompt.md. Share the old guide (or, for a brand-new tool, a description plus screenshots of the live UI) and it returns a clean, consistently-structured Word document saved as Guides/<Tool>-Guide2026.docx.

That prompt is the house style for guide content. The key rules it enforces:

Title is the app/service name only (e.g. “Microsoft Teams”) — no wrapper title.
Three fixed sections: Overview, Navigation, Quick Guide.
Friendly, concise, non-technical. No colours. No AI-sounding phrasing.
Document only what iOi staff use day to day — typically 2–4 key features, not everything that exists.
A screenshot of the live UI is the source of truth; anything unconfirmed goes in a Flags table at the end (removed once resolved).
Keep filenames consistent across versions so the Monday.com links don’t break.

Stage 2 — Publish it (HTML + PDF)

Build the HTML — pour the .docx content into the shared guide template (top bar, hero, contents, sections, cards, callouts). Drop the Flags table from the published version.
Screenshots — add the navigation-chrome PNGs (see below). No document/board content, so nothing sensitive appears.
Export — run ./make-pdfs.sh to generate the PDFs.

Full conventions and gotchas live in CLAUDE.md (AI) and README.md (human) at the folder root.

4 Screenshot checklist

Eight screenshots total — all navigation chrome only. Save each with the exact filename shown, into that guide’s assets/img/ folder.

#	Guide	What to capture	Filename
1	Monday.com	The My Work view	`mywork.png`
2	Monday.com	Top-right corner: notifications (bell) + in-tray icons	`topnav-icons.png`
3	Monday.com	Workspace dropdown expanded, showing all workspaces	`workspace-list.png`
4	Microsoft Teams	Left-hand sidebar (Activity, Chat, Calendar, OneDrive + Teams)	`sidebar.png`
5	Microsoft Teams	Teams and channels in the sidebar (where the channels are)	`teams-channels.png`
6	CharlieHR	Left-hand menu	`sidebar.png`
7	SharePoint	The app launcher (nine-dot grid) open	`app-launcher.png`
8	SharePoint	The SharePoint home page showing your team sites	`sites-home.png`

Folders

monday-tutorial/assets/img/      (shots 1–3)
teams-tutorial/assets/img/       (shots 4–5)
charliehr-tutorial/assets/img/   (shot 6)
sharepoint-tutorial/assets/img/  (shots 7–8)

Note: shots 4 and 6 are both sidebar.png — fine, because they’re in different folders.

Capturing on a Mac

Press Shift + Cmd + 4 — a crosshair with a live pixel-size readout.
Drag a tight box around the sidebar / menu / icons, then release (hold Space to reposition).
The PNG lands on your Desktop. Rename it to the exact filename and move it into the right folder.

Image sizes

Don’t resize the screenshots — these views are very different shapes (a thin icon strip, a tall menu, a wide page), so a single uniform size doesn’t make sense. The guides display each image at its native size, centred and never upscaled, so leave the captures as they come off the screen.

5 Generating the PDFs

Once the screenshots are in, regenerate all four PDFs with one command from the folder root:

./make-pdfs.sh

This exports each guide to pdf/<Tool>.pdf using headless Chrome. Upload those files to SharePoint and link them from Monday.com. To keep the Monday links from breaking, overwrite the same files in SharePoint on each update rather than uploading new copies.

6 Adding or updating a guide

Update content: edit the guide’s index.html (or, for a new tool, copy an existing guide folder as a starting point and replace the content).
Screenshots: add/replace PNGs in that guide’s assets/img/ and re-run the sips command.
Regenerate PDFs: run ./make-pdfs.sh.
Publish: re-upload the changed PDF (overwrite) and the HTML pack to SharePoint.

For the full conventions, see CLAUDE.md (AI instructions) and README.md (human overview) at the folder root.

7 The Monday.com hub

A single board acts as the entry point. One row per tool, linking that tool’s PDF in SharePoint:

Item (tool)	What it’s for	Guide (PDF link)
Monday.com	Plan projects, track tasks and deadlines, record programme impact	→ SharePoint PDF
Microsoft Teams	Messaging, meetings, day-to-day collaboration	→ SharePoint PDF
Microsoft SharePoint	Shared team files and documents	→ SharePoint PDF
CharlieHR	Leave, sick days, people directory, HR documents	→ SharePoint PDF

Use a Link column for the PDF. After uploading each PDF to SharePoint, copy its link and paste it into the matching row.