The outrage! The vague feelings of people I don't know taking things out of context may survive. If not, I'll bring them soup.
There are some unfortunately popular projects like Puppet over the past 20 years who tried to sell the lack of documentation as a positive, or just had incomplete and outdated documentation like Chef. ;] On the flip side, IETF RFCs, Python PEPs, and Rust RFCs are examples where specifications made things clearer and open to everyone. It's not enough to open source a thing without context or comments, the learning curve must be accounted for to make it as self-service and understandable as possible to people who have domain knowledge but have never used this particular thing before. OOTBE UX. Code maybe a communication of intended system behavior, but it is often too low-level and spread around to be relied upon as a singular, compact reference.
hi-v-rocknroll|1 year ago
There are some unfortunately popular projects like Puppet over the past 20 years who tried to sell the lack of documentation as a positive, or just had incomplete and outdated documentation like Chef. ;] On the flip side, IETF RFCs, Python PEPs, and Rust RFCs are examples where specifications made things clearer and open to everyone. It's not enough to open source a thing without context or comments, the learning curve must be accounted for to make it as self-service and understandable as possible to people who have domain knowledge but have never used this particular thing before. OOTBE UX. Code maybe a communication of intended system behavior, but it is often too low-level and spread around to be relied upon as a singular, compact reference.