I'd Like to Write the World Some Docs

It takes a special kind of person to enjoy writing documentation; not only do I have to write [ideally] working code, but now I have to write words that a human being can understand? What is this madness?!

Luckily, good documentation lives on outside your codebase. By following common documentation standards, we can generate comprehensive manuals that instruct others how to integrate with our software. After all, to code is human, but to document is divine.

✨ View slides ✨

Presentation History

• Cascadia PHP 2024 — October 24, 2024 (PDF, joind.in)
• Longhorn PHP 2023 — November 3, 2023 (PDF, joind.in)
• Beer City Code 2017 — June 10, 2017
• Lone Star PHP 2017 - April 22, 2017 (joind.in)

Resources

• Write the Docs - Global community of people who care about documentation
• CommonMark - Documentation for the CommonMark specification
• reStructuredText - Documentation for reStructuredText
• The composer.json schema (support) - Details for the "support" property within the composer.json schema

Tools & Services

Generating API Documentation from Inline Code

• ApiGen
• Doctum
• phpDocumentor

Building & Hosting External Documentation

• Daux.io
• GitHub Pages
• Read The Docs
• ReadMe
• Sphinx

Documenting HTTP APIs

• API Blueprint
• OpenAPI (née Swagger, start here!)
• RAML

Notes

• Title slide background taken from the 'Hilltop' spot from Coca-Cola's 1971 "I'd Like to Buy the World a Coke" campaign.