One of my good intentions of 2020 is to improve my documentation skills in my projects or where I contribute.
Since 2019 I am one of the maintainers of VVV and one of the first tasks that I chose to do was to close all the ticket about documentation stuff, 10 tickets where I did overall 43 commits.
This because the project for newcomers can difficult and as workshop about the usage of this tool I said that it was the case to do something about it.
The first thing that I learned over the fact that my English can be *bleah* that the reviewers of documentation has a lot of patience to check if everything is clear and if the fact can be explained better (Thanks Tom).
After this experience I chose to revamp the wiki stuff of WordPress Plugin Boilerplate Powered with a new page and new content. I read the Google documentation style guide as first step and get an idea about how the content, the various steps and how to reorganize the few pages that I already have.
Also after the experience of my first book I had few ideas about how to simplify the structure. I studied a bit also other documentation webiste that I like, as example the WP-Browser website.
Maybe copy that documentation is too much as first step but is important to have an idea about the final goal.
Anyway when I started on documenting myself about how to write better (or fight my will) I was thinking that Merge commits in the pull request view of GitHub was nice. After all I can get all my commits named like “fix” (and you are one of them that do that) to get merged with the pr title.
Also, I am a big fan of CommitStrip and I think that there is a commitstrip’s strip for any dev/sysadmin issue like this or this.
So on my searching I discovered the Conventional Commits project:
A specification for adding human and machine readable meaning to commit messages
The point is to have commits that can be parsed from another tool, as example they are following a specific standard, they start with a category:
build|ci|docs|feat|fix|perf|refactor|style|test|revert
Followed by a subcategory inside parenthesis and a colon, the rest is for the commit message itself. The official website include some exception and more information about the standard with also other tools.
I looked for the various tools that can validate my commit messages automatically, so I will be forced to follow this rules or I cannot work.
Hard ideas require hard measures [fake quote]
After trying various tools I found a tiny python script that can validate and do the commit for me, but I lost the original source of that… sorry.
In conclusion a new alias for my git workflow that I used on my first project from start just to test it. Now I want to use it on old projects to change the workflow in all my repository, I waited for a new project just to see if it is so blocking but it isn’t.
