Everyone Should Document All The Things!

PLEASE ABIDE BY OUR

CODE OF CONDUCT

If you need to report an incident, fill out our anonymous incident report form or email coc@drupalcampcolorado.org. Visit https://2019.drupalcampcolorado.org/code-conduct for the full code of conduct and contact information for the CoC team.

JOIN US FOR CONTRIBUTION DAY

Sunday, August 4, 2019

9:00am - 3:00pm

First-time, Mentored, and General contributions

Me Alex

  • Writing at https://read.finnsweb.io
  • Past employee at CU Boulder and more recently Highlights for Children
  • Currently on fun-employment to find the meaning of life
  • Will tell you the found meaning...after you hire me!
  • I'm also a super boring and pragmatic developer
  • I hope to bury you in links and references...40+ or so
0
 Advanced issues found
▲
 

Outline

  • Why I'm giving this talk

  • Who should document

  • What makes up documentation

  • When to write

  • Where it should go

  • Why document

  • Tools that help build out docs

  • Examples of Drupal and Symfony open source projects

Problem?

Textbook Example

D7 + Commerce + Custom Code + No Docs =

README.md Loud and Clear


# Adding Quotes To Checkout Process.

This module was modified for the [issue-link] issue. The business wanted 
to add a way for users to save and print out quotes. They decided to work 
that into the checkout process alongside the purchase order option.

I'm adding this readme for sanity's sake so the next person has some back 
story.

## The Payment Options

This module contains the "purchase order" and "quote" payment options 
during the checkout process. The "credit card" option is created by the 
commerce_stripe module.

The purchase order option allows a user to enter a special code rather 
than a credit card to make a purchase. The quote option allows a user to 
save the checkout items in a printable format that they can send to 
someone for approval.

...

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


// WHAT:
// Set the default value of age.
$age = 32;

// WHY:
// Discard the first element in the array because...
$age = $data[1]['_foo']['age'];

// Really Obvious Code
// The comments are moved to function declaration.
$age = getAge($data);


// MEAN:
// Richard did it this way cause he smells :P

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

/**
 * Static class providing Drupal specific Gettext functionality.
 *
 * The operations are related to pumping data from a source to a destination,
 * for example:
 * - Remote files http://*.po to memory
 * - File public://*.po to database
 */
class Gettext {


/**
 * Provides the node submission form.
 *
 * @param \Drupal\node\NodeTypeInterface $node_type
 *   The node type entity for the node.
 *
 * @return array
 *   A node submission form.
 */
public function add(NodeTypeInterface $node_type) {

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

/**
 * Executes interface translation queue tasks.
 *
 * @QueueWorker(
 *   id = "locale_translation",
 *   title = @Translation("Update translations"),
 *   cron = {"time" = 30}
 * )
 */
class LocaleTranslation extends QueueWorkerBase {

/**
 * Defines the node entity class.
 *
 * @ContentEntityType(
 *   id = "node",
 *   label = @Translation("Content"),
 * ...
 */
class Node extends EditorialContentEntityBase implements NodeInterface {

/**
 * Provides the node submission form.
 *
 * @param \Drupal\node\NodeTypeInterface $node_type
 *   The node type entity for the node.
 *
 * @return array
 *   A node submission form.
 */
public function add(NodeTypeInterface $node_type): array {

PhpStorm Is Your Friend


// @throws \Drupal\Component\Plugin\Exception\InvalidPluginDefinitionException
// @throws \Drupal\Component\Plugin\Exception\PluginNotFoundException

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

.travis.yml Fail


# Truth betold there was more to this in the original file...
before_install:
  # Check whether anything in the testing folder has changed.
  - git checkout ${TRAVIS_PULL_REQUEST_BRANCH}
  - git diff dev..${TRAVIS_PULL_REQUEST_BRANCH} tests/behat/features > foo.txt
  # Debug statement.
  - cat foo.txt
  - if [ $(wc -c <foo.txt) -le 2 ]; then echo "No change to beaht/features." && exit 1; fi

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


# Properly documented, could be improved:

┃  B  ↑  Foo#complicated

# Undocumented:

┃  U  ↑  Foo
┃  U  ↗  Foo#filename

You might want to look at these files:

┃ lib/foo.rb

Grade distribution (undocumented, C, B, A):  █  ▁ ▄ ▄

Only considering priority objects: ↑ ↗ →  (use '--help' for options).

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 

reST Example

**Bolded Text** and Stuff::

  // This is kinda like a code block?
  array.map(e => e.foo);

.. image:: netlify-dns-dashboard.png
    :width: 200px
    :align: center
    :height: 100px
    :alt: alternate text

Welcome to Sphinx Example's documentation!
==========================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

MkDocs vs Sphinx

0
 Advanced issues found
▲
 
0
 Advanced issues found
▲
 

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
0
 Advanced issues found
▲
 
0
 Advanced issues found
▲
 

MDX Proposal


import Video from '../components/video'

# My blog post

Here is some code:

```
my code!

```

And here's a video:

<Video width={300} src="video.mp4" />

Docz Project

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

Docz Example

---
name: Button
---

import { Playground, Props } from 'docz'
import { Button } from './'

# Button

<Props of={Button} />

## Basic usage

<Playground>
  <Button>Click me</Button>
  <Button kind="secondary">Click me</Button>
</Playground>

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

# build the image...
$ docker build . -t symfony-docs

# ...and start the local web server
# (if it's already in use, change the '8080' port by any other port)
$ docker run --rm -p 8080:80 symfony-docs

Symfony Docs

 

Drupal Docs Work

JOIN US FOR CONTRIBUTION DAY

Sunday, August 4, 2019

9:00am - 3:00pm

First-time, Mentored, and General contributions

Questions?

Image Credits

Document All The Things!

By afinnarn

Made with Slides.com

Document All The Things!

  • 1,281

More from afinnarn