Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/stevegrunwell/write-some-docs

Slides for "I'd Like to Write the World Some Docs"
https://github.com/stevegrunwell/write-some-docs

documentation reveal-js slides

Last synced: 3 months ago
JSON representation

Slides for "I'd Like to Write the World Some Docs"

Awesome Lists containing this project

README 

          
# ![Still from the 1971 "I'd Like to Buy the World a Coke" advertising campaign](resources/banner.jpg) 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](https://stevegrunwell.github.io/write-some-docs)** ✨



[![Four panel comic from Commit Strip, with a conversation between two engineers: First engineer: "Hey, I got assigned some bugs on your latest project but it looks like there's no documentation?" Second engineer: "What? Of course there's documentation! There's definitely a readme and there are some explanations on Jira. And maybe some explainers in Trello. And there's some information in Google Docs in a shared folder. Check if you can access it. It's not really up to date, but it's probably useful. And worst case scenario, there are plenty of contextual comments in the code." First engineer: Okay, so exactly what I said then...there's no documentation."](resources/commit-strip.jpg)](https://www.commitstrip.com/en/2021/11/10/no-documentation/?)



## Presentation History



* [Cascadia PHP 2024](https://cascadiaphp.com) — October 24, 2024 ([PDF](https://github.com/stevegrunwell/write-some-docs/releases/download/cascadia-php-2024/slides.pdf), [joind.in](https://joind.in/talk/aded3))

* [Longhorn PHP 2023](https://longhornphp.com) — November 3, 2023 ([PDF](https://github.com/stevegrunwell/write-some-docs/releases/download/longhorn-php-2023/slides.pdf), [joind.in](https://joind.in/talk/a402b))

* [Beer City Code 2017](http://beercitycode.com/) — June 10, 2017

* [Lone Star PHP 2017](http://lonestarphp.com/) - April 22, 2017 ([joind.in](https://joind.in/talk/b68e9))



## Resources



* [Write the Docs](https://www.writethedocs.org) - Global community of people who care about documentation

* [CommonMark](https://commonmark.org/) - Documentation for the CommonMark specification

* [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) - Documentation for reStructuredText

* [The composer.json schema (support)](https://getcomposer.org/doc/04-schema.md#support) - Details for the "support" property within the composer.json schema



### Tools & Services



#### Generating API Documentation from Inline Code



* [ApiGen](https://github.com/ApiGen/ApiGen)

* [Doctum](https://github.com/code-lts/doctum)

* [phpDocumentor](https://www.phpdoc.org)



#### Building & Hosting External Documentation



* [Daux.io](https://daux.io/)

* [GitHub Pages](https://pages.github.com/)

* [Read The Docs](https://readthedocs.com)

* [ReadMe](http://readme.io/)

* [Sphinx](https://www.sphinx-doc.org/en/master/)



#### Documenting HTTP APIs



* [API Blueprint](https://apiblueprint.org/)

* [OpenAPI](https://www.openapis.org/) (née Swagger, start here!)

* [RAML](https://raml.org/)



## Notes



* Title slide background taken from the 'Hilltop' spot from [Coca-Cola's 1971 "I'd Like to Buy the World a Coke" campaign](https://en.wikipedia.org/wiki/I%27d_Like_to_Teach_the_World_to_Sing_(In_Perfect_Harmony)).