The Payroc technical style guide is based on the Microsoft Writing Style Guide. See below for the Payroc guidance, but otherwise, refer to the Microsoft Style Guide.
Payroc technical docs are written in simple, straightforward language. They are not stuffy or formal. They might be simple on the surface, but that’s because we take the time to distill complex information into everyday language.
We make no assumptions about our audience and apply the principle of ‘explaining to your neighbour’. Would your neighbour understand what you’re trying to say?
We write mostly for online content, which is slightly conversational in tone.
Policy docs are more formal and are in .PDF format which is an audit requirement.
Product list TBD (being defined as part of brand strategy). This will demonstrate correct spelling, capitalisation, and text formatting of product names, how and when to abbreviate, and how to refer to Payroc products correctly.
Refer to the Payments Dictionary for payment terms and descriptions.
Format navigation paths like this: File | Menu | Button
Format procedural steps in lists: numbered first, then round bullets, then square bullets.
Limit of 3 tier lists. If you need more than this, split the content into smaller topics.
Format things in the UI (menu items and buttons, and so on) in bold.
GIFs show how to do a single task and should only be a few seconds long. They should not play automatically.
Videos show how to perform more complex processes which might include several tasks. They should be no more than 90 seconds long. If longer, consider splitting the content and making two or more videos.
GIFs and videos should be in mp4 format and hosted in Payroc Stream.
Use screenshots only when absolutely necessary. They’re difficult and time-consuming to maintain, and impossible to translate.
Illustrations are preferable to screenshots but be mindful of time spent creating them. Is the illustration worth it?
Code examples should be formatted as code snippets and should be easily copied and pasted.
Caption images and illustrations with a simple description of what it is, formatted in plain 8 pt text.
Provide alt-text for all images.
Write in short blocks of content separated into sections and subsections.
Structure content in a hierarchical way, leading with the most important information and getting into more detail as you go on.
Write task-oriented headings that signpost what the user has to do. For example, ‘Add card details’ not ‘Card details form’.
Maximum of level 3 headings. Split the topic if you need more.