4 ms·

In every team i joined at later stages, it was an uphill battle to try establishing this. In the end i was always the only one maintaining it and management saw

In every team i joined at later stages, it was an uphill battle to try establishing this. In the end i was always the only one maintaining it and management saw it as a waste of time. It is absolutely beyond me why decision journals are not standard. But i guess the source of the problem is that thorough evaluation of alternatives does not show immediate results to PMs and is against most devs "just starting to code" reflexes. Also if your choice is made by thinking "facebook also uses react and i already had to use it at my last job" it would be embarrassing to write this in a public document. (this is true for most EU projects, i really hope its different in the US)

shoo 7y ago
> Also if your choice is made by thinking "facebook also uses react and i already had to use it at my last job" it would be embarrassing to write this in a public document I agree that's not a very strong argument when making a tech choice, but still, it has more merit than a lot of resume-oriented-development I see: "we will use new tech X for this project because if we use the same old tech Y as we used for the last project, that will bore us, and there will be better job opportunities with other employers for the people working on the project if we gain experience in trendy new tech X". ... which is a pretty rational way for an individual to select tech, but not at all aligned with the interests of one's employer, or acting professionally & attempting to help one's employer make good decisions.
- Too 7y ago
  Actually both of the first arguments have a lot of merit, but can be phrased in a more professional way: "It's a well proven technology and many members on team already have experience with it so few deployment surprises expected and no training required." And what's more important, even if you write something embarrassing like "i don't know of any other tool, but this tool seems to be good enough" in the journal, that is very useful information to know in the future, vs "we did thorough evaluation of 4 different libraries and found out the others does not support important use case X".
closeparen 7y ago
I cringe when I come across the aftermath of decisions that sorely needed a reality check from a "just starting to code reflex" prototype or POC. Unchecked by the compiler or the need to actually work, complex design documents tend to derail into fantasy worlds. I want to read about what you ended up having to do after making contact with the real world, not what you thought you were going to do at the whiteboard stage.
- epicureanideal 7y ago
  I don't think he's saying you should write excessively before doing anything, just that enough context should be given to understand the decision at that point in time. At which point someone should start coding, and after real world experience changes the plan, that too could be added to the decision journal.
  - closeparen 7y ago
    Which is why I love the idea of a decision journal! Currently we only really document the upfront designs. Ongoing logs would add even more value.
  - jFriedensreich 7y ago
    exactly
- atoav 7y ago
  On the other hand I always get suspicious when a professional cannot describe me roughly what the road ahead entails — if someone is unable to explains this it usually means that they are either making it up as they go, that they never did this before or that they can't really communicate the things they do. And none of these are good signs. Of course you cannot expect a hundred percent accurate picture with all the nitty gritty details beforehand, but unless you are working solo having clear goals is really important. Programming really is about the decisions one takes at each step and the domain specific knowledge one encodes within the project. That is why reflecting and documenting every once in a while really makes sense.
jdsalaro 7y ago
There's another benefit to having a decision journal, even if you do it alone and not as a team or company-wide effort: it reduces the time you have to waste fighting misinformation. Companies bigger than a typical seed-stage startup usually come with an added level of bureaucracy. Products, tools, documents and others are usually created or pushed forward by different teams as a cross-functional effort. If you are the leader of such a project, the creator of a tool, methodology or document used by others, you will be expected to keep everyone in the gallaxy up-to-date with the details. Failing to do this will lead to certain personalities giving you a hard time. Suddenly people may start questioning your decisions in calls, emails and threads. You'll start wondering where all this skepticism comes from and will be forced to repeat yourself over and over again wasting valuable time. "Yes we did test whether to use X or Y architectures", "yes, we did test and consider this tool but it lacks feature Z". I'm likely not alone in considering the above a less than ideal situation to be in. Having a well organized and detailed decision journal allows you to stop the noise almost completely. Also, as others mentioned, it gives your thought process structure, keeps you honest, committed and makes evolving a deliverable overtime easier.

shoo 7y ago

> Also if your choice is made by thinking "facebook also uses react and i already had to use it at my last job" it would be embarrassing to write this in a public document I agree that's not a very strong argument when making a tech choice, but still, it has more merit than a lot of resume-oriented-development I see: "we will use new tech X for this project because if we use the same old tech Y as we used for the last project, that will bore us, and there will be better job opportunities with other employers for the people working on the project if we gain experience in trendy new tech X". ... which is a pretty rational way for an individual to select tech, but not at all aligned with the interests of one's employer, or acting professionally & attempting to help one's employer make good decisions.

Too 7y ago
Actually both of the first arguments have a lot of merit, but can be phrased in a more professional way: "It's a well proven technology and many members on team already have experience with it so few deployment surprises expected and no training required." And what's more important, even if you write something embarrassing like "i don't know of any other tool, but this tool seems to be good enough" in the journal, that is very useful information to know in the future, vs "we did thorough evaluation of 4 different libraries and found out the others does not support important use case X".

closeparen 7y ago

I cringe when I come across the aftermath of decisions that sorely needed a reality check from a "just starting to code reflex" prototype or POC. Unchecked by the compiler or the need to actually work, complex design documents tend to derail into fantasy worlds. I want to read about what you ended up having to do after making contact with the real world, not what you thought you were going to do at the whiteboard stage.

epicureanideal 7y ago
I don't think he's saying you should write excessively before doing anything, just that enough context should be given to understand the decision at that point in time. At which point someone should start coding, and after real world experience changes the plan, that too could be added to the decision journal.
- closeparen 7y ago
  Which is why I love the idea of a decision journal! Currently we only really document the upfront designs. Ongoing logs would add even more value.
- jFriedensreich 7y ago
  exactly
atoav 7y ago
On the other hand I always get suspicious when a professional cannot describe me roughly what the road ahead entails — if someone is unable to explains this it usually means that they are either making it up as they go, that they never did this before or that they can't really communicate the things they do. And none of these are good signs. Of course you cannot expect a hundred percent accurate picture with all the nitty gritty details beforehand, but unless you are working solo having clear goals is really important. Programming really is about the decisions one takes at each step and the domain specific knowledge one encodes within the project. That is why reflecting and documenting every once in a while really makes sense.

jdsalaro 7y ago

There's another benefit to having a decision journal, even if you do it alone and not as a team or company-wide effort: it reduces the time you have to waste fighting misinformation. Companies bigger than a typical seed-stage startup usually come with an added level of bureaucracy. Products, tools, documents and others are usually created or pushed forward by different teams as a cross-functional effort. If you are the leader of such a project, the creator of a tool, methodology or document used by others, you will be expected to keep everyone in the gallaxy up-to-date with the details. Failing to do this will lead to certain personalities giving you a hard time. Suddenly people may start questioning your decisions in calls, emails and threads. You'll start wondering where all this skepticism comes from and will be forced to repeat yourself over and over again wasting valuable time. "Yes we did test whether to use X or Y architectures", "yes, we did test and consider this tool but it lacks feature Z". I'm likely not alone in considering the above a less than ideal situation to be in. Having a well organized and detailed decision journal allows you to stop the noise almost completely. Also, as others mentioned, it gives your thought process structure, keeps you honest, committed and makes evolving a deliverable overtime easier.