Pangamma icon

Why I do not always trust documentation

Pangamma | PRO | 09/14/21 07:36:17 PM UTC (Edited) | 0 ⭐ | 308 👁️ | Never ⏰ | []
text |

2.17 KB

|

None

|

0 👍

/

0 👎

To elaborate
Docs change pretty quickly and any doc that has been around for longer than 2 weeks can already be outdated. In the previous cycle we had bugs filed because the implementation didn't match redlines, but then we went to fix them and it turned out there was an unrecorded conversation about deviating from red lines. Just minor things like that. I get it, we're human and we don't have time to be spending all of our lives on updating documentation. That's why I don't personally have a lot of trust in documentation that hasn't been updated recently. 
 I trust documentation based on how recently it was updated,
how visible it is (# people that might see it and decide to update it if it is invalid)
distance to the element it is describing (If I see comments in the code there is a high chance it is still accurate because people look right at the comments when changing the logic. Surely they would update docs when changing logic, right?)
 Same kind of thinking applies to VSO items. If my VSO item tells me to do X, and it gives me links to some instructions, I am going to assume that the instructions are up-to-date unless the VSO item specifically tells me to deviate from the instruction spec. And if a VSO item is 1 month old, it is probably 90% useless for telling you what the current project should be like. Chances are very high newer VSO items have come in to update previous requirements. 
 For design specs...  when I look at the spec that has been given for current sprint to describe a component, I assume that the spec is for the most part up to date, and I also assume the spec maker was trying to have page components fit existing patterns (like default react fabric ui styling, or a styling used globally within current project). I also assume the spec maker isn't perfect and they probably missed something. I know I would. It's a lot of detailing. My guess is that designers would forget to mention something because it isn't important enough to remember to include in the spec. So in those situations we can make "technical assumptions" and just wing it to the best of abilities (and hope no bugs are filed) or we can just ask designers what the "true" design should be. 

Comments