flaibo
Code Technical

Technical Documentation / README

README for our open-source CLI tool that syncs markdown files between filesystem and Notion, for developers with advanced CLI comfort

No card required

What this brief specifies

What's actually being documented

A Go CLI tool, a single binary distributed via Homebrew or direct download, requiring a Notion API key to authenticate.

Everything this README has to cover

Installation, authentication setup, common commands, the configuration file format, known limitations, and how to contribute.

Two jobs, one document

Has to work as the project's home page for a first-time visitor and as a fast reference for people who already use it.

What makes this hard

The core tension is that a first-time visitor and a returning user need the same document to behave in opposite ways: one wants a fast pitch and a sense of whether this solves their problem, the other wants to jump straight to the config format or a specific flag without rereading an intro. Trying the tool at all requires getting a Notion API key before a single command runs, so the section meant to hook a skimming visitor also has to walk them through setup friction that has nothing to do with the CLI itself. A generic README puts installation first and features later; it doesn't resolve keeping a returning user's lookups fast while a first-time visitor is still deciding whether that API key is worth clearing before they've seen any value.

FounderConsultantCorporateSmeEducator

Frequently asked questions

Carrying forward what the tool is and requires, everything the document has to cover, and the fact that it serves two different readers at once means the README an AI assistant helps write can separate the pitch from the reference, instead of blending them into one document. The next tool that needs a setup barrier explained to a first-time visitor, while keeping lookups fast for a returning one, starts from that same structure.

Ready to try this in Flaibo?

Get started free

Your context everywhere