Software How-To Guide Template

Template Overview

When users encounter friction in software, they want clear, task-oriented answers without philosophical essays. Following Diátaxis documentation principles, a How-To Guide focuses strictly on helping an active user solve a specific real-world problem through concrete steps. The Software How-To Guide Template structures user-facing help articles with clear preconditions, sequential UI actions, visual callouts, and troubleshooting resolutions.

Markdown Template Structure

Copy the block below or click Download .md File to add this template directly to your personal vault:

---
title: "How-To: [Task-Oriented Title Beginning with Verb]"
date_updated: [YYYY-MM-DD]
author: "[[Technical Writer / Support Lead]]"
difficulty_level: "[Beginner / Intermediate / Advanced]"
applies_to_versions: "[Oyma Desktop v2.4+ on macOS]"
estimated_time_to_complete: "3 minutes"
tags: [user-docs, help-center, how-to, documentation, support]
---

# How-To: [Task Title, e.g., Connect an Obsidian Vault for Automatic Meeting Exports]

## 1. What This Guide Covers
In this guide, you will learn how to configure Oyma to automatically export your meeting transcripts directly into an existing Obsidian vault directory on your Mac.

### Prerequisites Before You Begin
- Oyma Desktop v2.4 or higher installed and running.
- Obsidian installed with an existing local vault on your filesystem.
- macOS permission granted for local folder access.

---

## 2. Step-by-Step Instructions

### Step 1: Open the Storage Preferences Panel
1. Click the **Oyma** icon in your macOS menu bar, or open the main application window.
2. Press `Cmd + ,` to open **Settings**.
3. In the left navigation sidebar, select the **Storage & Vaults** tab.

> [!NOTE]
> All storage operations occur entirely on your local Mac disk. Oyma does not connect to any remote server.

### Step 2: Select Your Target Obsidian Directory
1. Under the **Automatic Vault Export** section, click the **Choose Directory...** button.
2. In the native macOS file picker dialog, navigate to your Obsidian vault folder (for example, `~/Documents/MyVault/Meetings/`).
3. Click **Select Folder**.

### Step 3: Configure Template Formatting & Naming
1. Under **Default Meeting Template**, select your preferred template (e.g., `Team Meetings & Governance`).
2. Set the file naming pattern to `{{date}}-{{meeting-title}}.md`.
3. Toggle the switch labeled **Export Audio Timestamp Anchors** to **On** if you want clickable audio timestamps inside your notes.

---

## 3. Verification & Testing
To confirm the export works correctly:
1. Start a 5-second test recording by pressing `Option + Space`.
2. Speak a quick test sentence and click **Stop & Transcribe**.
3. Open Obsidian and verify that a new Markdown file appeared in your target `Meetings` folder within 2 seconds.

---

## 4. Troubleshooting Common Issues
| Observed Problem | Probable Cause | How to Fix It |
|---|---|---|
| "Permission Denied when saving note" | macOS sandboxing blocked directory write access | Go to **macOS System Settings > Privacy & Security > Files and Folders** and ensure Oyma has access enabled |
| "Notes appear as unformatted text in Obsidian" | Obsidian Markdown formatting plugin disabled | Ensure Obsidian's native Markdown renderer is active in Obsidian settings |

---

## 5. Related Guides
- [How to Set Up Custom Markdown Frontmatter Templates](#)
- [How to Configure Apple Silicon Neural Engine Acceleration](#)

Filled Real-World Example

Here is a realistic example demonstrating how this template captures actual deliberations:

---
title: "How-To: Export Transcripts to Obsidian Vault"
date_updated: 2026-10-09
author: "[[Clara Bennett]]"
difficulty_level: "Beginner"
applies_to_versions: "Oyma Desktop v2.4+"
estimated_time_to_complete: "2 minutes"
tags: [user-docs, help-center, how-to, documentation, support]
---

# How-To: Export Transcripts to Obsidian Vault

## 1. Overview
Learn how to route meeting notes automatically into your Obsidian vault in under 2 minutes.

## 2. Quick Steps
1. Open Oyma Settings (`Cmd + ,`).
2. Go to **Storage > Vault Destination**.
3. Pick your local Obsidian folder.
4. Future meeting recordings will generate `.md` files directly in your vault with zero cloud transmission.

When to Use and When to Avoid

When to Use

• Use when authoring user-facing knowledge base articles, help centers, or documentation portals.
• Use to answer recurring customer support questions with structured, reproducible instructions.
• Use to establish a uniform tone and layout across technical documentation teams.

When to Avoid

• Avoid using for high-level conceptual marketing overviews.
• Avoid using for formal internal API endpoint specs (use API documentation spec instead).

On-Device AI Integration

Summarize your recording in Oyma with this local instruction:

Analyze the software how-to guide:
1. Verify that every instructional step begins with a clear, numbered imperative verb.
2. Check that the prerequisites section clearly states required permissions and software versions.
3. Formulate two additional common troubleshooting solutions for the troubleshooting matrix.
Output in structured Markdown.

Your data remains securely on your Mac with zero cloud exposure.