Live and recent posts from across the Fediverse tagged #documentation, aggregated by home.social.
📦 mddoco v2.2.2 is now on PyPI
Markdown to HTML/PDF document converter — themes, table of contents, Mermaid diagrams, native charts, Jinja2 and CSV context.
Install / upgrade:
pip install --upgrade mddoco
🐍 PyPI: https://pypi.org/project/mddoco/2.2.2/
🧑💻 GitHub: https://github.com/massyn/mddoco
📦 mddoco v2.2.1 is now on PyPI
Markdown to HTML/PDF document converter — themes, table of contents, Mermaid diagrams, native charts, Jinja2 and CSV context.
Install / upgrade:
pip install --upgrade mddoco
🐍 PyPI: https://pypi.org/project/mddoco/2.2.1/
🧑💻 GitHub: https://github.com/massyn/mddoco
It's interesting how the #web evolves, only to cycle back to plain text files. After years of increasingly complex #documentation platforms, we're back to Markdown files. #Anthropic hosts a lot of #Markdown files under https://code.claude.com/docs/en/, not for humans but for machines to read. And this was exactly the original idea behind #HTML, to be read by maschines. #plaintext
📦 mddoco v2.2.0 is now on PyPI
Markdown to HTML/PDF document converter — themes, table of contents, Mermaid diagrams, native charts, Jinja2 and CSV context.
Install / upgrade:
pip install --upgrade mddoco
🐍 PyPI: https://pypi.org/project/mddoco/2.2.0/
🧑💻 GitHub: https://github.com/massyn/mddoco
A number from September changed how I write a how-to: on the estate's docs sites, pages at search positions four to ten were clicked 0.31% of the time. Three clicks in a thousand appearances.
Something is reading those pages, though. Assistants fetch a page when somebody asks a question, answer, and move on. The person who asked never sees the page.
The pages fetched most weren't the best-written or the most complete but the ones whose first screen was a quotable command. Open with preamble and the assistant quotes the preamble.
So the rule is now:
• A how-to opens with the thing that does the job: the command, config block or API call, ten lines at most, plus one sentence saying what it does.
• A reference page opens with whatever a person came to look up.
• Everything the page used to say first goes underneath.
afmpeg's remux guide went from 132 words before the first line of code to 27. The paragraph about stream copies is still there, word for word, directly underneath.
You can check it from the shell: count the words between the title and the first code block or table. Under a hundred is answer-first. It's a number you can put in a merge request, and it takes the argument out of review.
One exception: tutorials. Their reader has chosen to sit down and learn, and the walk is the thing they came for.