Problem?

Textbook Example

D7 + Commerce + Custom Code + No Docs =

README.md Loud and Clear

But That's Not A Readme!!!

Not Again!?!

D7 + Commerce + Custom Code + Some Docs =

Open Your Eyes, It's Beautiful

What Is "Documentation"?

"Material that provides official information or evidence or that serves as a record."

The why more than the what...

"Good code is self-documenting."

A Continuum

• Version control
• In-code comments
• Function/class-level comments
• ...Annotations sidebar
• Synthesized docs in wikis
• ----------------
• Ephemeral documentation in issue trackers and Stack Overflow
• Blog posts and "cookbooks" for specific use cases

Version Control

• "Hidden documentation"
• Committing atomically and writing longer descriptions avoids putting comments in code
• "Always write commit messages as if you are explaining the change to a colleague sitting next to you who has no idea of what’s going on."
• ...but who actually writes long descriptions in Git messages? (50 character rule)
• using Gitflow can be helpful here, e.g. "feature-1734" branch leads to an issue summary with more context

In-code Comments

• Comment on why you did something and not what you are doing

• Review them before you make a pull request

• "A junior dev will tell you what they are doing, a mid-level dev will tell you why they are doing it this way, and a senior dev will tell you why they aren't doing it a different way."

• Put them on their own lines

• Good, bad, ugly of comments in code

Examples

Function/Class Comments

• Generally what you see on API sites like api.drupal.org
• Can be autogenerated from code
• Can use annotations for metadata related to the code in the class or function
• Can be foiled by "{@inheritdoc}"

Examples

Annotations

• “Annotations basically let you inject behavior and can promote decoupling.”

• The configuration is all in one place

• Don’t have to inherit from a class in Doctrine as you do in Propel

• Plugins like Entities and Controller Annotations in Drupal

• Can be used for properties as well as methods and classes

• It can be parsed and added to API docs which is not as easy to do with YAML files

• Many people don’t like them

Examples

PhpStorm Is Your Friend

Synthesized Documentation

• Generally what you see on OSS project documentation sites or GitHub wikis
• These are guides to whole subsystems of a library or framework
• Generally, allow the reader to contribute without touching the project's codebase
• Can easily get out-of-date with the actual codebase
• Can get messy and incoherent without templates

Symfony Example

Note the...

• warning of version differences
• version selector
• quick edit link

Who Should Write Documentation?

Everyone! Yay!

Write What You Know

• Don't tell the newbie "We could always use more documentation"
• That's like letting someone who just learned how to write complete a textbook
• Devs have context only devs know
• BDD tests can be written by a QA team member
• Product features and troubleshooting can be documented by the support team

Depends On Team Size

• I've only worked in small teams of about 10 - 15 developers including QA and Ops
• Chances are you have many hats if you work in a small team
• Larger organizations might have dedicated people doing this
• Developer Avocados might be in on the fun and try to pull you in as a "Hero"

Where Should It Go?

Where You'll See It

• If it's hard to get to then people will never read your hard work after you're gone
• "/docs" directory akin to "/tests"
• Placing them in a separate repo makes sense for permissions and project management's sake
• Use crosslinks

Reminders

• Placed on 50+ "bundle" repos
• Placed in central repo since the steps could change
• Yes, the release process wasn't followed all the time 

When To Write Documentation?

Some Say At The Beginning

• Some advocate for "Readme Driven Development"
• Backlash at documentation is in part due to the "thorough documentation" waterfall project management days
• In an agile methodology, the fast iteration cycle and "sprinting" make it hard to justify writing thorough documentation

Blog As You Go

• Try to get your employer behind the idea of blogging as a way to help your company's bottom line
• You can jot down notes to be filled in later so that your development time doesn't suffer
• We need more "stories" of general developer day-to-day work vs. general, abstract documentation
• I correct code from time to time due to writing blog posts
• Blog posts can serve as documentation and be linked for more details in general documentation

Nudges At The End

• CI tools provide a great place to add checks before code is merged in
• You can fail a Travis test run if no changes are made in the docs directory
• You can also make a private GitHub app that adds a check or comment when a PR is made
• ESDoc can show you a report on documentation coverage

.travis.yml Fail

docs-checker GH App

Inch

• A documentation analysis tool for the Ruby language
• No overall grades
• Gives grades of A, B, C, or undocumented to each class, module, constant or method in a codebase
• Priorities to be documented: public methods, more parameters

Example Run

Why Document?

Let's Start With Some Research

Three Types of Developers

• Systematic - understand the API from a top-down approach 
• Opportunistic - start coding immediately from a bottom-up approach
• Pragmatic - combine top-down and bottom-up approach

“They are less willing to read documents that focus on conceptual information, although conceptual information, such as background information on the problem or domain addressed by the API, determines how efficiently API documentation can be used."

(Jeong et al., 2009; Ko & Riche, 2011)

No Time For Concepts!

Other Tidbits

• They tended to use their own code samples over again when starting a new project
• Redundancy helps to embed knowledge directly in a developer’s mind. Provide info in text and in code comments.
• Enable fast use of API/tool via automation setup scripts rather than steps.

Comment Haters

• Comments can’t be trusted

• Allows for sloppy code over self-documenting code

• Place comments in “hidden documentation” a.k.a the git log

• “Clutter” or “pollute” the codebase.

“Indeed, the ratio of time spent reading versus writing is well over 10 to 1. We are constantly reading old code as part of the effort to write new code. ...[Therefore,] making it easy to read makes it easier to write.”

- Robert C Martin

We Read A Lot!

Documentation Tools 

• The Drush project uses Read the Docs among many others
• Quickstart guide uses Sphinx, a Python-based documentation generator
• Sphinx parses reStructuredText and also has directives that allow generation of markup
• MkDocs is an alternative that parses Markdown 

reST Example

MkDocs vs Sphinx

• Read the Docs author opinionated about not using Markdown for docs
• Comparison mentioning fewer output formats for MkDocs
• Sphinx generates API docs from docblocks
• You can use Markdown in Sphinx
• I liked MkDocs because it's familiar and has file watching built-in

MDX Format

• MDX is the "best of both worlds" combining JSX and Markdown
• Takes away the complaint that Markdown isn't extensible
• Allows you to use a whole slew of React components and knowledge

MDX Proposal

Docz Project

• New documentation tool that uses MDX
• Powered by Gatsby and Gatsby themes
• Can be used for a style guide akin to Storybook

Docz Example

Others

• phpDocumentor also includes reports and graphs for inheritance diagrams, errors in documentation, deprecation notices, and @todos still in the code
• Swagger helps to generate interactive documentation for APIs built around the Open API specification
• ...and more

Swagger UI

Documentation Projects

api.drupal.org

• As you might think, "There's a module for that"
• Place core and contrib code within a built Drupal 7 site to be parsed
• Uses the PHP-Parser project to make an AST of PHP code

• A crap ton of menu paths load the individual types of code - files, functions, classes, etc.

• Uses hook_load() to take wildcards in paths and load the data for page callbacks. This is interesting because there is already a hook_load for nodes.

Local D7 API site

Drupal User Guide

• Written in AsciiDoc format, which I know little about
• “The source uses AsciiDoc markdown format, which can be compiled into DocBook format, which in turn can be compiled into HTML, PDF, and various e-book formats.”
• Feeds imports the files to parse them periodically in batches
• The asciidoc_display module can parse and render XHTML output from AsciiDoc source files
• Can submit one source file for updates or create a patch if multiple files need to be changed

User Guide Footer

Symfony Docs

• Created with reST and Sphinx
• A dockerized solution can be set up in two commands
• Quick edit link goes back to the text editor on GitHub for making a pull request

Symfony Docs

Drupal Docs Work

• The #documentation channel on the Drupal Slack is the best place to go to find out what's currently happening
• The Docs Working Group isn't too active these days
• A Documentation Initiative is slow going but working on one-page guides
• They are working on a Getting Involved Guide to orient new contributors