Teamplify Style Guide

# Teamplify Style Guide Check this when writing for Teamplify.   ## Why use a style guide? This style guide helps Teamplify use consistent language for all components of written communication. Communication includes all pages of the application, all pages of the website, and various communication miscellany, like tweets, help pages, and blog posts. Besides consistency, the other goal of this style guide is to _save everyone time_. Instead of making a guess about the best way to say something, or digging through old Slack channels, why not check the style guide? If something doesn't exist, add it to the style guide! ## Brief guide to writing interactions * Describe UI elements, buttons, and navigation in **bold.** This gives users a visual anchor when jumping back and forth from the application to the text. * Head to **Settings**, then click **Save** * Put changeable, user-inputted text in `monospace` * In the **ID** field, type `1234` * Put procedures in numbered steps 1. Begin a list 2. End a list * If the order doesn't matter, list items in bullets * Item 1 * Charles Dickens * In instructions, put the result of the action first. This helps users scan to find the action they want to do. ```diff X Go to settings and click **Remove** to delete a member. ✓ To remove a member, go to settings and click **Remove** ``` ## "What's new" Template Using a template makes repeated content easier to write. This structure, in turn, makes the content easier for the reader to scan. This is especially true if they read multiple articles, as they will become used to the structure. ```  # Create a new widget  If you can't create a widget, you have to do everything manually. With this feature, you can use widgets to automate each step of the build. For example, instead of adding a floo to every user, use a floo widget to add floos to everyone at once.  To add a widget, you'll need an account. Then, head to **Settings > Widgets**, and follow these steps: 1. ...  After you create a widget, it'll appear in the "Widgets" module. If nothing appears, make sure you configured the floo.  Widgets will save you time when doing the same thing over and over. We hope creative ways to use them! ``` ## Teamplify terminology :::info Except for "ivelum," capitalize all words at the beginning of sentences. ::: ### Business terms Terms about doing business with Teamplify and ivelum * **Teamplify**: the name of the application. A noun and an adjective (e.g. Teamplify workspace) - _avoid:_ teamplify (in lower case) * **ivelum**: the parent company of Teamplify - _avoid:_ Ivelum (uppercase) ### Subscription terms * **Teamplify Cloud**: The Teamplify plan on the cloud, - _avoid_: Teamplify cloud (you should capitalize both words) * **Teamplify On-premises**: the specific on-premises plan - _avoid_: Teamplify on-premises (you should capitalize both words) * **cloud**: in the context of Teamplify, all services on the cloud, i.e. everything that's not on-premises - Unless referring to an account or plan (i.e. without "Teamplify" in front of the word), do not capitalize * **free plan**: the non-trial, feature-limited plan - _avoid_: Free plan (capitalized) * **on-premises**: - _avoid_: self-hosted, onpremises, selfhosted, on premises, on premise, on-premise, On-premises - "on-prem" is acceptable when space is tight or if on-premises has been used once - Unless referring to an account or plan (i.e. without "Teamplify" in front of the word), do not capitalize * **Pro plan**: the paid subscription - _avoid:_ pro plan * **trial**: the full-featured trial period - _avoid:_ Trial plan (capitalized) * **Unlimited**: full-featured subscription - _avoid_ unlimited plan ### Teamplify actions The things that Teamplify does, and objects that Teamplify works on. * **action**: anything a member does in one of their connected accounts that creates a work artifact (e.g. a commit in Github) * **activity**: Whenever a member uses one of their connected accounts to perform an action that leaves a digital artifact (e.g. a commit), that counts as work activity. - Activity can be measured across multiple periods, on the level of the member and of the team. * **analysis**: some calculation or visualization that Teamplify does on the activity * **analyze**: when Teamplify performs analysis - _avoid:_ analyse * **notifications**: https://teamplify.com/notification-types/ - Any message that Teamplify sends to a chat or email. Notifications are either scheduled or triggered by member actions * **notify**: when Teamplify sends a notification ### Statuses and balances * **balance**: amount of time off remaining for a status * **earned time**: when time is issued to a balance after some amount of days worked - _avoid_: "accrued time," except when it's important to be precise (e.g. for an HR or accounting audience) * **status**: any period that a member designates for time off or special working days https://teamplify.com/member-status/ * **time off** - any business days when a member works doesn't work, e.g. vacation, sick day, half day - when used as a noun, do not hyphenate. - when used as an adjective, do hyphenate - _avoid_: off-time, time-off (as a noun), time off status(as an adjective), offtime * **working day**: any day that a member works - _avoid:_ work day, workday (unless it's the special status of a freelancer) ### Roles and application spaces * **account**: has multiple meanings: - An organization's account with Teamplify - a member's account with Teamplify - a member's account with a service that Teamplify connects to * **admin**: an organization member who can invite, create workspaces, configure status behavior * **members**: An individual in an organization, either admin or non-admin. - members can belong to multiple teams, and multiple workspaces. - _prefer:_ the term "member" over "user." * **organization**: collective entities who do business with Teamplify * **report**: has multiple meetings: - A weekly report that a member writes - A Teamplify generated report that analyzes some period of activity * **team**: a group of one or more members who belong to a workspace. Each team's activity has its own panes in a workspace * **workspace**: the pages of the Teamplify application. Where users go to see collected activity ### Inviting and connecting * **approved email domain**: an email domain that admins can send invites to * **unassociated account**: an account found in an integration, * **connected account**: third-party accounts that a member links to Teamplify * **connect**: when a member connects a service to Teamplify * **integrate**: when an organization links a service to their workspace * **integration**: a service linked to a Teamplify workspace https://teamplify.com/integrations/ * **invite**: when an admin invite a member to their Teamplify workspace * **service**: a third-party account that Teamplify connects to - In some cases, use the full phrase "third-party service" to make it clear that the text is not referring to Teamplify A workspace might have an integration with a service. This integration can find 50 accounts associated with that service. ### UI Elements As much as possible, avoid describing UI elements. This future proofs the writing from UI changes, and helps confusion if there are multiple versions. Instead, try to give an outline of what to do. Hopefully the UI is mostly self-evident! * **calendar**: the collected work of a team or member, arranged in a period, e.g. week, day, year * **page**: a major component of the Teamplify UI, probably noted by the first path after {workspace}.Teamplify.com (e.g. https://ivelum.teamplify.com/teams/) * **section**: a subpage, probably a subpath of a page - _avoid_ pane, panel" ## Not in the guide? Check Google (their developer style guide) :::info Teamplify's style guide should be a tiny addition on top of the big guides. ::: Google and Microsoft have spent a lot of time, money, and brainpower making style guides. Besides, their written material appears everywhere, so readers are used to their terms (much content overlaps). Where it doesn't make sense to invent a custom Teamplify rule, the best thing to do is check what the big players do. When figuring out a term, follow these steps: 0. Is it in the Teamplify guide? If not... 0. Use the [Google style guide](https**://developers.google.com/style/) as a reference. Why Google first? That has been the first source to check since we started. No reason to stop now. Besides, Google's is slightly more oriented towards SaaS applications. Useful links: * [Describing UI elements and interaction](https**://developers.google.com/style/ui-elements) * [Writing lists](https**://developers.google.com/style/lists) 0. If Google doesn't have something use the [Microsoft Style guide](https**://docs.microsoft.com/en-us/style-guide/) _Why Microsoft?_ It's the most comprehensive style guide. Useful links: * [Creating scannable content](https**://docs.microsoft.com/en-us/style-guide/scannable-content/) 0. If you still can't find what you want to say, come up with a term and add it to the guide. Also if you found something in the big manuals that Teamplify should use often, add it to the guide.