Most projects don't have a docs problem. They have a "nobody wants to open the docs file" problem: the README is three commands and a TODO, the architecture lives in someone's head, and the setup steps are out of date by the second release.
The writing itself is rarely the hard part. The friction around it is: previewing Markdown, drawing the one diagram that explains everything, checking an API name, and keeping the tone consistent. Here are 8 Mac apps that remove that friction, grouped by the part of the job they help with.
Write the Markdown
1. Typora, for seeing the README as you write it
Typora hides the Markdown syntax and shows the rendered result in place, so tables, code fences and headings look like they will on GitHub while you type. It also handles Mermaid diagrams, a [TOC] table of contents, and export to PDF, HTML and Word.
Cost: $14.99 once, activates on up to 3 devices, with a 15-day free trial. typora.io
2. iA Writer, for long docs that need focus
When the doc is a design proposal or a migration guide rather than a quick README, iA Writer's Focus Mode dims everything except the sentence you're on. Style Check flags filler and clichés, and it marks pasted or AI text in a different color from what you typed, which is handy when you're reviewing a draft.
Cost: $49.99 once for Mac (20% education discount), with a 7-day free trial. ia.net/writer
3. Obsidian, for the notes that turn into docs later
Debugging notes, decisions and "why we did it this way" scraps belong somewhere searchable. Obsidian stores everything as plain Markdown files in a local folder, so a good note can be copied straight into the repo when it's ready to become real documentation.
Cost: free with no sign-up; optional Sync is $4 a month and Publish is $8 a month (billed annually). obsidian.md/pricing
Draw the diagram
4. Mermaid, for diagrams that live in the repo
Mermaid turns text into flowcharts, sequence diagrams and more. GitHub renders a fenced code block tagged mermaid right inside Markdown files, issues and pull requests, so the diagram gets reviewed in the same diff as the code it describes. The Mermaid Live Editor is useful for sketching before you paste.
Cost: free, open source. mermaid.js.org
5. Excalidraw, for the whiteboard-style sketch
Some ideas don't fit neatly into boxes and arrows from a text syntax. Excalidraw gives you a hand-drawn style canvas that exports to PNG or SVG for the README, and it can convert Mermaid into an editable drawing when you want to rearrange things by hand.
Cost: free; Excalidraw+ is $6 a month per user for cloud saving, team workspaces and more AI requests. plus.excalidraw.com/pricing
Get the details right
6. Dash, for checking API names without a browser tab
Docs go stale when you write a function signature from memory. Dash searches 200+ offline docsets and 100+ cheat sheets with fuzzy search, plugs into VS Code, Xcode, JetBrains IDEs, Alfred and Raycast, and can generate a docset from your own project's HTML docs.
Cost: free to download; the license is a yearly subscription ($28.20 a year at the US checkout). kapeli.com/dash
7. DraftKey, for the sentences between the code blocks
The code samples are usually fine. It's the "this module handles..." paragraphs and the release notes that take the longest. DraftKey sits in the menu bar and suggests the next few words as you type in your Mac apps, so you press Tab to accept and keep going. Select a paragraph to fix it, make it shorter or clearer, or change the tone, then review the result before you insert it.
Cost: $4.99 once for up to 3 Macs, with 500 free words per Mac to try it. Needs Apple Silicon, macOS 14+ and 8 GB of RAM (about a 1.12 GB download). getdraftkey.com
8. Vale, for enforcing the style guide before merge
Vale is a prose linter: you write rules in YAML (or start from published Microsoft, Google or Red Hat styles) and it flags violations in your editor or in CI, the same way ESLint flags code. It understands Markdown structure, so it skips code spans, URLs and fenced blocks. On a Mac it's one brew install vale away.
Cost: free, open source. vale.sh
The whole docs kit at a glance
| Job | App | Cost |
|---|---|---|
| Write and preview Markdown | Typora | $14.99 once |
| Long, focused docs | iA Writer | $49.99 once |
| Notes that become docs | Obsidian | Free |
| Diagrams in the repo | Mermaid | Free |
| Hand-drawn sketches | Excalidraw | Free |
| Offline API lookups | Dash | $28.20/yr |
| Drafting the prose | DraftKey | $4.99 once |
| Style checks in CI | Vale | Free |
Four of the eight cost nothing, and you only need one of Typora or iA Writer.
What's the part of writing docs you put off the longest: the README, the architecture overview, or the changelog?

Top comments (0)