It will help you to improve your skills or how to understand how to start this journey!
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.
