Documentation
How to install DocLamp, read its scores and act on them.
On this page
Getting started
- A site admin installs DocLamp from the Atlassian Marketplace.
- The same admin chooses the spaces DocLamp may analyze. DocLamp reads nothing before that choice.
- The analysis starts right away, in the background. On most sites the overview fills up within minutes.
- Everyone opens it from Confluence's Apps menu, then DocLamp.
Anyone on your site can open DocLamp, and each person only sees the spaces they can already view. The app reads with its own Atlassian account, so pages with view restrictions are never analyzed.
Choosing the spaces
- Site admins choose the analyzed spaces the first time they open DocLamp. They can change that choice at any time in DocLamp's Administration tab, or from Atlassian Administration, under Apps, Connected apps, DocLamp, Configure.
- Spaces created later are analyzed automatically, unless you turn that option off.
- Space admins can also Exclude from DocLamp their own space, from its page in DocLamp, and include it again later.
- An excluded space is never read: no daily analysis, no analysis on demand, not even to count links. The data kept for it is erased.
The overview
The first screen sums up your whole site:
- at the top, where monitoring stands: when the last daily cycle finished, how many spaces it analyzed, and when the next one starts;
- the site score, weighted by the size of each space, with its trend over the week and the share of well-prepared pages;
- how many issues have been fixed since tracking started, and how many pages have none left. A deleted page does not count, and neither does a change of scoring method;
- the starting score: where the site stood at the very first analysis of its spaces, and how far it has come since. When the scoring method has changed in between, it is shown without the gap;
- the new pages: how many pages were created in the last 30 days, and how many of them are well prepared. Once there are at least 5 new pages and 5 older ones, DocLamp compares the two, so you see whether what your team writes now is better prepared than what it wrote before;
- how many pages are well prepared, need work, are fragile or critical;
- under the score, the site score curve. Detailed curve shows it day by day, month by month over two years, and year by year for as long as DocLamp is installed. Export the history (CSV), in the same window, gives you every score kept, space by space;
- Where to start: the least prepared spaces, to open first;
- the issues that weigh the most across the site, and those shared by several spaces, which usually come from a shared habit rather than a one-off slip;
- All spaces, from the weakest to the best prepared, each with its main obstacle. Click a space, or find it with Open a space above the table, to open its last analysis. Spaces never analyzed come last, with an Analyze button;
- during the last ten days of a trial, and during the month before an annual subscription renews, a summary of what DocLamp measured, which you can publish as a Confluence page for your management. It quotes only site-wide totals, no page and no space.
Site admins also get an Administration tab, with the monitoring status and the choice of spaces. Everyone else sees the overview alone.
A space in detail
A space opens on its last analysis, with no wait. Its score comes with its trend over the week, the issues fixed since tracking started, its starting score (the score of its first analysis) and its new pages, compared with older ones. The same card shows page quality and space structure, and how the pages break down; under it, the score curve. Detailed curve shows it day by day, month by month and year by year. Run the analysis again after your fixes to see the score move.
Below, three tabs:
- To fix starts with Where to start: the pages with several issues, lowest scores first. Open a page and fix everything in one go. Then what holds the whole space back, and Issue by issue, ranked from the heaviest to the lightest, so starting at the top gains the most points. Each issue explains how to fix it, with examples, and See all pages shows every page it affects.
- Trend shows the space score day by day, month by month and year by year.
- Share and manage: Publish as a Confluence page creates a dated report in that space, filed under “DocLamp reports”, which anyone who can see the space can read. You can also export the list of pages as a CSV file. The Share button next to the space's name opens the same in a window.
In Share and manage, space admins also find Erase this space's data, which deletes every analysis stored for the space. Monitoring analyzes it again at its next pass; to stop that, use Exclude from DocLamp. Reports already published stay in Confluence.
Reading the scores
Scores run from 0 to 100.
- Each page starts at 100 and loses points for every issue found, more for serious ones. An empty page scores 0: it gives Rovo nothing to answer from.
- The page average reflects the quality of the space's pages.
- The space score reflects how the space is organized as a whole.
- The space's overall score is the lower of the two. A space is only as good as its weakest spot.
| Score | Status |
|---|---|
| 80 and above | Well prepared |
| 65 to 79 | Needs work |
| 50 to 64 | Fragile |
| Below 50 | Critical |
Very small spaces get an indicative score, since a handful of pages says little about how a team documents its work.
We keep improving the analysis. When an update changes a score, the app says so, and no alert is raised for it.
What DocLamp checks
DocLamp looks at each page, and at how each space holds together, from six angles:
- Structure: pages that are unfinished or hard to follow;
- Clarity: wording that only insiders understand, and that Rovo can misread too;
- Freshness: statements that may no longer be true;
- Connections: pages cut off from the rest of your documentation;
- Findability: spaces where the right page is hard to find;
- Jira context: work your pages mention, without a way for Rovo to reach it.
In the app, issues are ranked by impact, and each one explains how to fix it, with examples from your pages and the list of pages it affects.
The score on a space's home page
The DocLamp score macro shows a space's score where its team works: its status, its trend over the week, the issues fixed since tracking started, its starting score and its new pages. It updates with every analysis.
- To add it, edit a page of the space, usually its home page, type “/DocLamp” and insert the macro. DocLamp never adds it for you: it does not change existing pages.
- It always shows the space it sits in, and only to people who can see that space.
- “See the details in DocLamp” opens the app.
Daily monitoring and background analyses
- Every chosen space is analyzed again once a day. You're alerted when a space's score drops noticeably from one day to the next.
- Site admins see the monitoring status in the Administration tab, and can start a pass there with Run a pass now.
- An analysis started from the screen has 25 seconds to finish. Larger spaces are analyzed in the background on the server, in a few minutes, and the screen shows the progress.
- Space admins can request a background analysis, up to once an hour per space and 20 times a day per site.
Limits
- Up to 10,000 pages are analyzed per space. Beyond that, the app tells you and analyzes the first 10,000.
- Personal spaces and pages with view restrictions are not analyzed.
- The app's own report pages are left out of the analysis.
- The app is available in English and French, following each person's Atlassian profile language.
- Most checks work in pages written in any language. The few that read the wording itself understand English, French, German and Spanish, and the app tells you when pages in another language were only partly checked.
Questions
My score changed, but nobody edited the space.
Either we improved the analysis (the app then says the method was updated), or links from other spaces changed: links to a page are counted across your whole site.
A page is missing from the results.
It probably has view restrictions, which the app can't read. The space page tells you how many pages it skipped.
Does DocLamp send our content to an AI?
No. The analysis runs inside Atlassian Cloud and calls no AI service. The Privacy Policy has all the details.
Something looks wrong.
Write to contact@doclamp.com. The Support page lists what helps us answer quickly.