Documenting my open source work also means documenting myself

In November 2016 I decided to participate in National Novel Writing Month (NaNoWriMo), and instead of writing a novel, I would write open source documentation.

It was my personal National Documentation Writing Month. NaDocsWriMo.

I kept the goal of 50,000 words, which I did not meet. But I did write a lot of docs! I ended up doing a decent amount of cleanup of old repositories, improving personal maintenance tools, and created better methods for supporting and communicating about the many open source projects I create.

These blog posts!

I started work on these end-of-year blog posts as part of the documentation I created. Since attending The Evergreen State College, I've enjoyed writing self-evaluations of my work. At Evergreen there aren't grades for overall coursework. Students either get credit or they don't, and both students and professors write evaluations of their work, the challenges they faced, and how they might improve. You can think of these blog posts as a similar exercise. A way to reflect on my work, figure out what was effective, and what I ought to do next.

Setting up development environments

I rewrote a guide to setting up computers with Node.js and Git development environments.

Through rewriting that guide and considering the difficulty that can come up when onboarding new JavaScript/Node.js developers, I created dev-env-status, an electron app that checks a user's computer to see if Node & Git are installed and available, and gives installation instructions if not. I created this with the intent of holding Node.js install parties call Dev Env Party, a kind of reusable event format for helping new Node.js users get started by helping them install the necessary dependencies on their computers.

Personal documentation repos

Most of my NaDocsWriMo time was spent on improving older repositories, and as I went through them I realized I needed to better document the work I was doing at a higher level.

I needed places where folks could ask me questions, get an overview of the projects I'm working on, see what demos I had created, and read notes from my development process.

I created four GitHub repositories to address this:

ask

Want to chat about code, beer, coffee, pizza, books, design, journalism, etc? Do it! 👍.

I made the ask repository as a generic place for folks to ask questions about open source software as well as other topics.

This is similar to "ask me anything" repos other folks have created.

projects

A list of open source projects I work on. I've realized that I work on a lot of different projects. They are all in different stages and it can be hard to keep track of them.

I can barely keep track so why would I expect you to know what all I'm up to?

The projects repository gives a good overview of what I work on.

notes

The notes repository is where I take notes on ideas, learning, projects, daily tasks, etc.!

examples

The examples repository is a directory of demos, examples, and experiments I've created.

Cleaning up GitHub repos

I went through and improved many open source projects in November and December. I found that I was doing roughly the same tasks repeatedly,and created this rough checklist for improving my projects:

Tests

Improve tests as much as possible:

Travis

Set up Tracis CI for continuous integration testing:

Status

Consider the status of the project:

Documentation

Collaboration

global development dependences

List of development dependencies I use that make sense as global dependencies:

dependencies

development dependencies

Common development dependencies across projects:

Install dev dependences:

npm i -D documentation tape tap-spec standard

npm scripts

Standard npm scripts across repos:

"deps": "dependency-check . && dependency-check . --unused --no-dev && ncu",
"docs:api": "documentation build index.js -f md -o docs/API.md",
"docs:build": "npm run docs:api",
"lint": "standard",
"test:no-lint": "node tests/*.js | tap-spec",
"test": "npm run lint && npm run test:no-lint"

There's still more to do!

I still have a lot of repositories that could use help updating with the above checklist. If anyone is interested in helping to maintain projects I work on, please open an issue on the relevant issue queue.

A tool for managing common files in repositories

As part of this cleanup work of repos, I created a command-line tool called sdv that quickly generates files like README.md, CONTRIBUTING.md, CONDUCT.md, examples, docs, & tests, directories and more. I originally created it just for myself to make it easier to setup these common files, and after using it for a couple of months I'm considering generalizing it for others to use.

Good practice

As I've been documenting my work and improving project documentation I've realized that providing better documentation of my work is a lot like documenting the products of companies and organizations. Thinking about how I can better support people that use my open source work is great practice for supporting folks using software in general, and I'm now feeling more prepared to support users of web apps that I create.

Working on your documentation

I'm always happy to work on documentation, and am open for contract work creating and improving documentation and the tools used to produce those docs. You can email me at sethvincent@gmail.com.

See also