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
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:
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.
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.
The notes repository is where I take notes on ideas, learning, projects, daily tasks, etc.!
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:
Improve tests as much as possible:
- write at least one test (if applicable).
- improve existing tests.
Set up Tracis CI for continuous integration testing:
- create .travis.yml file
- add travis integration to repo (I've been using menubar app travis-comrade for this!)
Consider the status of the project:
- Is this project stable, in development, or deprecated?
- Does this project need a new maintainer?
docsdirectory that contains:
README.mdfile describing available docs
examplesdirectory with at least:
README.mdfile describing available examples
basic-usage.jsfile showing simple example
testsdirectory with at least:
README.mdfile documenting how to run tests
index.jsfile with basic tests
- add/improve contributing guidelines
- add/improve code of conduct
- add contact information & links to places to chat about project
global development dependences
List of development dependencies I use that make sense as global dependencies:
- add npm-check-updates and dependency-check as the
depsnpm script to check whether dependencies are up to date and used in files
Common development dependencies across projects:
Install dev dependences:
npm i -D documentation tape tap-spec standard
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.
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 email@example.com.