Guide for Creating Guides

This guide is for Microkeeper staff who write or edit guides and FAQs. It explains how customers use guides, how every guide is structured and written, and how to use the guide editor so your changes save the way you expect.

AI agents writing guides follow the same rules, kept in guide-writing.mdc. If you change a rule here, change it there too.

This guide covers how to:

1. Choose the right page type and lay out a guide.
2. Write headings, steps and wording that work on their own.
3. Use the editor's blocks, screenshots and links.
4. Fill in a guide's Title, Description and Keywords.
5. Write an FAQ.
6. Check a guide before publishing it.

How customers find and read guides

Customers reach a guide in four ways:

• The guides menu: reading a category in order, using the Previous and Next links at the bottom of each guide.
• The Guides link in the app: it opens the guide for the page they're on, where one exists.
• The help search and AI tools: these split every guide at its headings and show one section at a time, without the rest of the guide around it.
• Links from FAQs and other guides: these usually point at one section.

Only the first way starts at the top. Write every section so it makes sense if it's the only thing the customer reads: its heading names what it covers, and its text doesn't depend on the section before it.

Where the facts in a guide come from

A guide describes what the customer sees today, not what an older guide said.

• Copy button names, field labels, tabs and menu paths from the screen, exactly as they appear.
• Write for payroll version 9 onwards. New businesses start there, so the screens in every guide are version 9 screens. Only the Payroll Version guide talks about older versions.
• Use the MK Journey test business to follow a workflow end to end and to take screenshots. It has realistic venues and staff, and nothing you do there affects a customer.
• Where Microkeeper has a known limitation, describe the workaround. Don't present a limitation as how it's meant to work, and don't promise a fix.
• If you can't confirm something on the screen, leave it out and ask the development team.

Choose the guide's page type

Every guide is one of five types. The type decides which sections it has and their order.

If a guide is turning into two types, for example a task guide with a long explanation of a concept in the middle, split the concept into its own guide and link to it.

Lay out a task guide

Most guides are task guides. The MYOB, Reckon and Xero integration guides all follow this layout and are good models.

Start with the introduction

Use an H1 matching the guide title, then two or three sentences on what the guide helps the reader do. If the guide covers several jobs, follow with "This guide covers how to:" and a numbered list of them, in the order the guide covers them.

Say what's needed before you start

Give anything that has to be set up first its own section, for example "Prerequisite: Configure your accounting suite to Xero". Link to the guide that explains it rather than repeating it.

Give each task its own section

Each task gets an H2 that names it, the menu path to get there, then numbered steps. Use H3 for parts of a task or for options within it, such as the Breakdown By options in the integration guides.

Add troubleshooting when customers get stuck

Add a troubleshooting section when there are real problems customers run into on that screen: support tickets, FAQs, or something that confused you while following the steps. A short guide with nothing that goes wrong doesn't need one.

Put troubleshooting last, with one expandable per problem. Write each expandable's heading as the customer's question: "Why is nobody in my pay run?"

Finish with related guides

Link the guides a reader is likely to need next, such as the guide for the following step.

Separate every H2 section with a horizontal line, and keep each section to one topic of roughly 50 to 400 words.

Write headings that make sense on their own

A heading is often all a customer sees in a search result, so it needs to name its subject.

Don't use H4 for structure, and don't repeat a heading within a guide.

Write to the reader as "you"

Use Australian English, present tense, short sentences and plain words. Talk to the reader directly.

Write steps as a numbered list with one action in each step. Avoid "simply", "just", "easy" and "quick": if it isn't easy for the reader, those words make it worse.

Bold, quotes and menu paths

• Bold names on the screen: click Complete Payrun.
• Put text the reader types in "quotes": enter "Weekly" as the pay cycle name.
• Write menu paths with ">" between each level, bolding the last one: Menu > Settings > General > Global > System Settings.
• For something inside a page, keep going: Menu > Settings > Employees > click Edit for the employee > Employee Profile.

Capitalisation

• Capitalise Microkeeper features and modules: Location, Role, Job, Group, Rate Rules, the Roster Calendar.
• Use lowercase for the general idea: "add a job to the Jobs list", "each employee's locations".
• Write buttons, menus and fields exactly as they appear, including their capitals.
• Spell other products the way they do: Xero, MYOB, Reckon.

Words to use

Use the editor's blocks

Click Insert block on the editor toolbar to add a callout, expandable, steps or cards. Each example below is the real block, as readers see it.

Use a callout only when the reader would miss something important without it. A guide with a callout in every section has none that stand out.

Warning callout

For anything that deletes data, replaces existing work or pays the wrong amount.

Info callout

For context, tips, and limits such as which plan or version a feature needs.

Error callout

For a problem the reader has to fix before they can continue.

Success callout

For how the reader knows a step worked.

Expandable

For troubleshooting questions, and for detail most readers can skip. The heading is the question; the answer is hidden until the reader clicks it.

Steps

For a short process shown at a glance, most often on an overview guide. Use a numbered list instead for detailed instructions.

Cards

For linking a set of guides, such as the guides in a category. Link each card's title.

Replace the default "Step title" and "Card title" headings, and remove any empty steps, cards or expandables, before you save.

Quotes and tables

Use the toolbar's quote button for a worked example that illustrates a step, such as a sample pay calculation.

For tables, choose the Row borders table style and include a header row. Keep tables narrow enough to read on a phone; if a table needs more than four or five columns, split it.

Add screenshots to a guide

Screenshots and diagrams support the text; they never replace it. Screen readers, the help search and AI answers only read text, so anything an image shows, such as a step, a setting or a table of values, must also be written in the guide.

• Take screenshots in the MK Journey test business or another test business, never in a customer's account.
• Set the browser zoom to 100% and crop to the part of the screen the step is about. Aim for 300 to 600 pixels wide so the image reads on a phone.
• Use PNG for screenshots, JPG for photos and SVG for simple diagrams.
• Name the file in lowercase words with hyphens that describe it, for example "complete-payrun-export-step.png".
• After uploading, set the alt text to describe what the screenshot shows, align the image left, and remove any fixed width so it shrinks on a phone.
• Put the screenshot after the step it shows, not before.

Delete or replace a screenshot

Clicking the image's bin icon deletes the image file from the server, and Undo doesn't bring it back. If you cut an image to paste it elsewhere, click Cancel when asked whether to delete it.

Cloudflare keeps showing a deleted or replaced image for a while. To check your change, open the guide in a private window on another server by adding syd., mel. or bri. before microkeeper.com.au in the address. Do this once, at the end of your editing session, or Cloudflare caches that server's copy too.

Link to other guides

• Link a word or two that says where the link goes, never a whole sentence and never "click here".
• To link a whole section, use the heading's id: the heading text in lowercase, with punctuation removed and hyphens for spaces. For example, guides.php?guide=payroll-software#payments-classification-chart opens the Payments Classification Chart heading.
• To link a particular sentence or passage, use the browser's Copy link to highlight. The guide opens with that passage highlighted.
• Both kinds of link stop working quietly when the words they point at change. If you rename a heading or reword a highlighted passage, update the links to it in the same session.

Fill in the guide's Title, Description and Keywords

When you're logged in as Microkeeper staff, three fields appear above the guide. They're what search engines and the browser tab show.

• Title: up to 60 characters, usually the same as the H1.
• Description: up to 165 characters, one sentence on what the guide helps the reader do. Search engines show it under the title.
• Keywords: lowercase phrases a customer might search for, separated by commas, for example "xero integration, payroll xero".

Prompt for writing the Description and Keywords

Paste this into an AI tool, followed by the guide's text:

Write the Title, Description and Keywords for this
Microkeeper help guide.

Title: up to 60 characters, naming the feature or task,
for example "Xero Integration".

Description: one sentence, up to 165 characters, saying
what the reader can do with the guide. Australian English,
written for a business owner or payroll officer. No
marketing words such as "easy" or "powerful".

Keywords: 3 to 6 lowercase phrases a customer might type
into a search engine, separated by commas. Include the
feature name, and "payroll", "roster" or "timesheet"
where it fits.

Reply with the three fields only.

Guide:
[paste the guide text here]

Check the result against the guide before saving it: the description should match what the guide covers.

Write an FAQ

FAQs answer one question each, and the help search shows them alongside guide sections.

• Write the question the way a customer would ask it, for example "Why can't my staff clock on from their phone?"
• Answer in a few sentences that solve the problem, then link to the guide section with the full steps.
• Choose the existing category that fits, such as Payroll, Superannuation, STP or Roster, rather than adding a new one.
• Before adding an FAQ, search for an existing one on the same question and improve that instead.

What the editor removes when you save a guide

Guides are cleaned when they're saved, to keep them safe to show publicly. Saving removes:

• ids on headings and other elements. The contents sidebar creates heading ids again each time the page loads.
• The setting to open a link in a new tab, so links open in the same tab.
• Comments in the HTML.

Pasted text loses its formatting, so pasting from Word or a web page is safe. Format the text again with the editor's toolbar.

Check a guide before you publish it

1. Every button, label and menu path matches what's on the screen today, on payroll version 9.
2. The guide follows its page type, and every heading makes sense on its own.
3. No section is empty, and no heading is repeated.
4. Callouts are only where they matter, and any troubleshooting questions are worded the way customers ask them.
5. Every link opens the right guide and section.
6. Screenshots load, read on a phone, have alt text and show no customer data.
7. The Title, Description and Keywords are filled in.
8. FAQs and other guides that link into this guide still point at the right section.