While working on documentation pages and using the LLM for documentation, @vmassol noticed that LLMs tend to capture the whole screen when taking screenshots, instead of just the relevant part. So a new question came up around how we should crop screenshots when adding them to doc pages.
Any unrelated section that is captured that can change in time will become oudated.
Option 2: Cropped screenshot
Pros
Smaller, lighter images.
Focuses attention directly on what matters.
Less likely to go stale from unrelated UI changes.
Cons
Loses context: harder for a reader to locate the element within the broader page/wiki structure.
Can feel disconnected from step to step if there’s no context to the overall page.
Proposal
We could do a mix of the two options:
First step of a procedure**: use a full-context screenshot, so the reader can locate the general area of the wiki/page where the action starts.
Subsequent steps**: use cropped screenshots focused on the relevant UI area only, since the context has already been established.
If the documented UI element is not part of the side panels, we could crop those panels out of the screenshot even when we’re otherwise going for a “full context” shot.
WYT? Which approach do you find more relevant? Thanks!
Is that what you’re proposing for option 2? Namely:
If the area is inside the main content view, take a full screenshot of that view?
If the area is in a side panel, take a screenshot of only that panel?
Actually, maybe we don’t need to define any more specific rule and CC or a human doc writer will be clever enough to figure it out What would be interesting to test is what CC would do with just just the relevant area of the UI. I’m trying it now and will report.
* Show only what the reader needs in order to act: the UI element the step is about, plus the nearest landmark that tells them where that element is (the panel holding it, the screen title above it, the list it follows). Crop the rest away, side panels included when the element is not one of them. The test is whether a reader who doesn't have the wiki in front of them can still tell where the action happens.
** The first step of a procedure is the exception: keep enough of the interface for the reader to find the starting point…
** Choose the ##size## that fits the region you framed, instead of framing a whole window to fill ##extra##…
Reword the capture-width bullet to say “crop a region that is already that wide rather than shrinking a wider capture into it, and never enlarge a smaller one”.
Reword the red-square bullet to add: “the ones the step asks the reader to act on: on a step that says to review a list, the square goes around the list, not around the button underneath it.”
Let me know if you like it and I’ll push both changes.
**3. dev.xwiki.org — [Working with Attachments](https://dev.xwiki.org/xwiki/bin/view/Community/DocGuide/WorkingAttachments/)** (version 3.1)
The three edits from `docguide-screenshot-framing.txt`: the new framing bullet with its two sub-bullets, the reworded capture-width bullet, and the reworded red-square bullet. Read back byte-identical to what I sent, 0 rendering errors, and I confirmed both old strings are gone from the rendered page.
**I made one edit beyond the handoff**, and you may want to veto it. The size list said `##extra##: width of the image : 960px; (used for whole interface screens)` — which directly contradicts the new sub-bullet telling authors *not* to frame a whole window to fill `extra`, seven lines above it. I dropped the parenthetical, matching the other three sizes which carry none; the new bullet now supplies that guidance. One word and I'll restore it.
I also reworded the red-square bullet slightly against the handoff's draft: its version used an em dash where a comma does the work, which the documentation conventions call out, so it reads "…UI element(s), meaning the ones the step asks the reader to act on:".
## Still open
- **The Gallery example** — the handoff's "Optional", and its unanswered question 2. The section would demonstrate its own point better with the before/after pair. Not done; say the word and I'll attach `current/` vs `proposed/` to that section.
- **A margin rule in the guide.** I deliberately did *not* add one, since it's new normative content for a community guide and you scoped this to the handoff. But today's whole defect was a red box overlapping the content it marked, and nothing in the guide forbids it. Suggested clause for the red-square bullet: *"Leave a small even margin between the square and the element so the border never touches or covers the content."*
## Two errors in the handoff, worth correcting before it's reused
- **A2 is wrong about where the content lives.** It says the steps are in the `content` field of the `DocApp.Code.DocumentationClass` object. That property is `null`; the content is the **page's own content**. The same paragraph then says not to touch the page's own content, so it contradicts itself. Following A2 literally would have left the page unchanged while writing to a property the tooling deliberately avoids.
- **The dev.xwiki.org REST note is a misdiagnosis.** It records that `/rest` returns 404 for `Community.DocGuide.*` and concludes reads must go through `?viewer=code`. The real cause is the path: it's a nested page, so the reference needs `spaces/WorkingAttachments/pages/WebHome`, and the wiki id is `dev`, not `xwiki`. Authenticated REST reads and writes both work fine, which is what made the exact round-trip above possible.
What would be interesting to test is what CC would do with just 