Using README.org
The last few months have been rough. Today I "finished up" one of a set of small "feel good" projects I have been doing to learn things and, you, know, feel better. Much quick project: org-git-hooks.
#more
While admittedly tiny, it's nice to consolidate some code that I'd
duplicated and fun, in that the 400 line ~README.org file contains all
of the code, documentation, "build" configuration, and licensing.
Why Would You Do That?
I'm using the README.org structure some projects and I often forget to regenerate README.md from it when I commit.
I realize "I'm stuffing everything into a README.org file" may raise questions somewhat similar to those it purported to answer.
Let's talk about me, for a minute.
Writing More by Writing Less
Brevity is one of the things I most struggle with.
I am have some not-quite-trivial code (a "batch script" for Emacs, and some shell scripts to interface with githooks). Unfortunately, I wrote it quickly and it's turned out to be handy. I have copies in more than half-a-dozen projects, I think.
In happier news, peering across these different incarnations, I see only small variations. We might say the "existing feature surface" for my "problem domain" was small. Naturally, I added a feature.
Often my first pass at documentation is aspirational.
As I started picking my favorite versions of each program and flowing them together in between source blocks, I was thinking. I wondered:
-
How to "consolidate" the edits from the different projects using these scripts?
-
How I would integrate the "stand-alone feature" into each of the projects?
-
How much of this will I really do, and when?
Fairly quickly I had my README.org caught up with what was already done, and filled with notes on what I wanted. The file now lead with some "for company documentation", authoritative sounding wild guesses at the final design. After this was the actual program sources, and finally the licensing boilerplate.
At this point there really wasn't any duplicated language. There was a little repetitiveness in code, but I wasn't concerned: it was hastily written and about to get some thoughtful edits.
As I begin my edits I was already drifting from the documentation I'd sketched at the top of the README. I'd initially planned to start by adding environment variables directly into the post-commit script. The initial directions were to edit that file.
Between writing those directions and starting to update code, however, I'd hit upon the .env file and realized it at once for the better approach. Not only would edits directly to the programs be unnecessary, it's more intuitive and also more flexible. Projects often have other means to create shell/environment variables; they seem well "socialized" vs shell script more generally.
Eventually my .env was creating variables. The post-commit script "sourced" (loaded the variable defined by) it. The "build.el" emacs batch scripts was similarly updated. Repetition and hard-coded filenames were gone. It was time to bring the "narrative" parts of the README back into step with what I'd coded.