As a follow up to my TODO review, I’ve rolled out the first draft of a writing habit, together with an over-enginered tool, habit, to enforce it.

The Life Cycle of a Post

The life cycle of a post A nerdy term, maybe more plainly, the steps for writing posts. ;P is the sequence of stages and states a post will undergo through. I’ve devised two stages each with its own set of states: In retrospect, the naming is a little bit too mouthful and I might change them later. The reason behind all these present tense is my (clumsy?) attempt to emphasize the dynamic, continuous nature of each phase.

• draft: scaffolding, fledging, editing
• post: polishing, reviewing

Goals of Topic

In consistence with my view of post as idea-observational diary, the transition between stages and states are not strictly defined. In fact, I would rather like free-style transitions among them. Posts represent ideas, as ideas evolve so should posts.

Draft

Influenced by the Jekyll’s way of organizing posts, draft is simply a stage when posts are not deemed as befit publishing.

Scaffolding

This may sound like just a fancy way to say outline, but by using a different word I try to emphasize the importance of goal-setting. Just like building scaffold, once erected, the building is constructed as such. The later phases are discouraged to stray too far away from the initial goal Maybe it’s not only my own bad habit, all programmers may like to do something smarter, better or more. The end result is usually over-engineering, pre-mature optimization and unmet deadline. Sigh….

Fledging

At this state, I am conducting research and gathering raw materials for the post in work. Throughout the years, I’ve learned the importance of extensive references and citations. They are not merely there to make the work look more professional, but to support the post, establish connections among different knowledge bits and most importantly make the post maintainable.

Connections: In an age of ubiquitous access to Internet and fast searching, memorizing exact details is usually not worth the effort. It’s more important to construct a mind map holding references to those details.

Maintainable: You might not even remember you write this post a year later. How do I reach this conclusion? Why do I say that? I read some of my diaries in high school and could not believe they were written by me I was shocked by the beautiful and sensational sentences (in Chinese for sure) in my old diaries. I know I’ll never be able to write something like that. Sigh, I used to be a sensitive youth and now I’m just “old and mean”.. I used to think the extensive references following the article are only for research papers. Now I believe they are necessary for anyone who takes their thoughts serious. They’re required to make long-term post reviewing possible.

Editing

A large potion of the work in this state is about formating. However, I’ll remind myself this state is more about the style: remove all unnecessary parts, check all references, check the spell, make sure the main body focused on topic and move all smartness to side notes.

Post

A post enters this stage when it’s published. There several guidelines I’ll try to follow:

1. publish early, publish often A variant from the famous Release early, release often.: this principle is particularly important. Whenever a post takes too long to publish, it’s a time to think whether the original goal is too big and whether it’d be better to divide into multiple smaller posts.
2. Though rare, it’s OK to transition back to draft. In such a case, a question should also be asked whether it’s better to write a follow-up post.

Polishing

Typos, ill-formatted text, wrong references, extra style tweakings and other non-content-modifying changes.

Reviewing

The changes that modify the content belong to this state. The maintainability of the post will be very important at this state. Just like code, posts are works of thoughts, in the long run, it’s the maintenance that costs the most.

Tool Enforcement

I’ve written a tool in node called habit to enforce the stages and states above For now it’s a tool only for writing post, but I have the intention to grow it into a generic habit enforcer. node is picked as I’m most familiar with it and shell scripts are not good for long-term growth. For the record, I indeed implemented some functions of habit in fish shell script before migrated to habit.

How the tool enforce the habit

Check out the README for details. It suffices to say habit helps the author focus on a single post; unify, provision and validate Git commit message to track stages and states; manage posts’ meta data, draft creation and post publishing At the time of writing, these are just plans. Jekyll-compose is not sufficient for our needs..

Over-engineered? Yes for now, but it’s better to have a tool to remember rules for us than rely on forgetting human mind.

The design&implementation - CLI in Node

See CLI tool development wiht nodejs - an example TODO Planned.

∎