This is the beginning of a discussion I would like to initiate, expecting a few behavioral rules that would help us to set and keep the level of understanding our product across all team members.
This as most of the advice we share should be taken with a "grain of salt" - meaning that this rule should be used while also using the sense for common sense.
For starters, here is my first proposal:
1. Keep a private log of what you do
As the context, I want to use @JeroenVinke's current work on componentizing the KendoUI scheduler, project that starts with defining what are all bindables going to be. I am sure that this is a subject that we all would like to understand better and Jeroen could explain to use how it is done in KendoUI world.
Now comes the part where I ask for using the common sense: I am not proposing that everyone doing something relatively new, starts by writing a user manual about what he is getting ready to do. Instead, I propose to keep a running log in the form of a GitHub issue, where one can easily jot a few comments, drop a section of relevant code, insert a screen shot or make a link something else relevant in this situation.
This issue (named "my running log for componentizing xxx") should be kept open (in the GitHub sense) and the author could maintain it in a form of a section (comment field) per day for increased readability)
Once a specific project is finished (or sooner if a documentation effort starts in parallel, a bit staggered) the data from this "container" will be used to write documentation, to look into by a poor soul who got trapped in the customer support, not being the author of this component, or by someone else who wants to further work on this component later.
In summary, my proposal is to create and maintain a document that is a partial memory dump, knowing well that it would make most sense (when read later) to the author, as markdown is likely not the best way to serialize someone's thoughts.
As with all other proposals I will make, this should not be perceives as an order :-) Anyone who finds the value in doing that, will do it (I will for sure)
This is the beginning of a discussion I would like to initiate, expecting a few behavioral rules that would help us to set and keep the level of understanding our product across all team members.
This as most of the advice we share should be taken with a "grain of salt" - meaning that this rule should be used while also using the sense for common sense.
For starters, here is my first proposal:
1. Keep a private log of what you do
As the context, I want to use @JeroenVinke's current work on componentizing the KendoUI scheduler, project that starts with defining what are all bindables going to be. I am sure that this is a subject that we all would like to understand better and Jeroen could explain to use how it is done in KendoUI world.
Now comes the part where I ask for using the common sense: I am not proposing that everyone doing something relatively new, starts by writing a user manual about what he is getting ready to do. Instead, I propose to keep a running log in the form of a GitHub issue, where one can easily jot a few comments, drop a section of relevant code, insert a screen shot or make a link something else relevant in this situation.
This issue (named "my running log for componentizing xxx") should be kept open (in the GitHub sense) and the author could maintain it in a form of a section (comment field) per day for increased readability)
Once a specific project is finished (or sooner if a documentation effort starts in parallel, a bit staggered) the data from this "container" will be used to write documentation, to look into by a poor soul who got trapped in the customer support, not being the author of this component, or by someone else who wants to further work on this component later.
In summary, my proposal is to create and maintain a document that is a partial memory dump, knowing well that it would make most sense (when read later) to the author, as markdown is likely not the best way to serialize someone's thoughts.
As with all other proposals I will make, this should not be perceives as an order :-) Anyone who finds the value in doing that, will do it (I will for sure)