How to Create and Publish an Internal How-To Guide

Creating a how-to guide takes less time than you might expect. The platform is built so that the mechanics — titling, tagging, saving, publishing — stay out of your way, letting you focus on the actual knowledge you want to share. This page walks you through every step from a blank editor to a published, searchable guide your teammates can find and use.

Steps to Create a Guide

Click 'New Guide' from your Internal KB dashboard

Open the Internal KB section from the main navigation and click the New Guide button in the top-right corner of the dashboard. This opens the guide editor in a new tab with a blank canvas ready for your content. If you don't see the New Guide button, check that you have contributor access — contact your workspace admin if the option is missing or grayed out.

Add a title

Type your guide's title in the Title field at the top of the editor. A strong title makes your guide easy to find and sets clear expectations for readers before they click.

Keep these principles in mind when writing your title:

Be action-oriented — Start with a verb that describes what the reader will accomplish: "Configure," "Set up," "Troubleshoot," "Request," "Export."
Be specific — "Set up Okta SSO for Slack" is more useful than "Slack setup." Specific titles rank higher in search and reduce confusion when multiple guides cover similar topics.
Use the words people search for — Think about what a colleague would type into the search bar. Mirror that language, including product names, acronyms, and tool names your team actually uses.
Keep it under 70 characters — Titles longer than 70 characters get truncated in search results and the guide library sidebar.

Select a category or team tag

Use the Team dropdown to assign ownership of the guide to your team. Then apply one or more topic tags from the tag picker — type a keyword to search existing tags or create a new tag by typing a name and pressing Enter.

Choosing the right category and tags determines where your guide appears in the browsable library and which related-content suggestions it gets paired with. If your organization uses product areas, select the relevant product area from the Product Area field as well. You can update all of these at any time after publishing.

Write the content

The editor supports rich text, markdown shortcuts, and embedded media. Structure your content so readers can scan it quickly and follow along step by step:

Open with a short intro paragraph — One to three sentences explaining what this guide covers and who it's for. Readers should know immediately whether they're in the right place.
Use numbered steps for sequential actions — If the task requires doing things in a specific order, use a numbered list. Each step should describe one discrete action.
Add screenshots for complex UI — Upload images directly into the editor by dragging them onto the canvas or clicking the image icon in the toolbar. Add a brief caption explaining what the screenshot shows.
Include code snippets where relevant — Wrap commands, file paths, config values, and code samples in code blocks. Always specify the language so syntax highlighting works correctly.
Use callout boxes sparingly — Notes, tips, and warnings draw the eye, but they lose impact if overused. Reserve them for genuinely important caveats or shortcuts.

Add metadata

Scroll to the Guide Details panel on the right side of the editor and fill in the following fields:

Author — Defaults to your account, but you can add co-authors if the guide was a collaborative effort.
Last updated date — Set this to today's date. Update it every time you make a meaningful change to the content so readers know how current the information is.
Related guides — Search for and link up to five related guides or SOPs. These appear in the "See also" panel at the bottom of your published guide and are also used to power related-content suggestions for other articles.
Description — Write one to two sentences summarizing what the guide covers. This text appears in search result previews.

Publish or save as draft

When you're ready, click Publish to make the guide visible to everyone in your workspace with Internal KB access. If you're not done yet, click Save Draft to preserve your work without publishing.

Draft guides are only visible to you (the author) and workspace admins. They do not appear in search results, the guide library, or related-content suggestions until you publish them. If a colleague tells you they can't find your guide, check whether it's still in draft state.

After publishing, you'll see a confirmation with a direct link to your guide that you can share with teammates immediately.

Formatting Your Guide

Good formatting makes the difference between a guide that gets read once and one that teammates bookmark and return to. Follow these conventions to keep your guides clear and consistent.

Headers — Use H2 (##) for major sections and H3 (###) for subsections within them. Avoid going deeper than H3; if you need a fourth level of hierarchy, consider splitting the guide into two separate articles.

Numbered lists vs. bullet lists — Use numbered lists for steps that must happen in sequence. Use bullet lists for options, examples, or items where order doesn't matter. Don't mix the two in the same list.

Callout boxes — Use them for the right purpose:

<Note> — Background context or a clarification the reader should be aware of
<Tip> — A faster or smarter way to accomplish something
<Warning> — An action that could cause data loss, access issues, or other negative consequences
<Info> — Supplementary detail that's helpful but not critical

Images — Keep screenshots focused. Crop out irrelevant UI chrome and annotate with arrows or highlights if the relevant area isn't obvious. Aim for images no wider than 1200px for clean rendering on all screen sizes.

Code blocks — Always use fenced code blocks with a language tag, even for single-line commands:

gcloud auth login --update-adc

{
  "region": "us-east-1",
  "output": "json"
}

Write one guide per task. If you find yourself adding a major section that feels like a completely separate topic, split it out into its own guide and link between them. Shorter, focused guides are easier to find, easier to maintain, and easier to read than long multi-topic documents.

Using Guide Templates

Templates give you a pre-formatted starting point so you spend less time thinking about structure and more time writing content. The platform ships with three built-in templates you can select when creating a new guide.

The Quick Reference template is designed for guides that need to be scanned, not read top-to-bottom. It opens with a one-sentence summary, followed by a two-column reference table and a short list of key commands or values. Use this template for things like keyboard shortcuts, CLI flag references, or environment variable glossaries.

Best for: cheat sheets, command references, config lookups.

To use a template, click the Templates button in the editor toolbar before you start writing. Selecting a template replaces the blank canvas with the template structure — you fill in the content, and the formatting is handled for you.