3 ms·

> It is properly documented? IMO If you're really staking a key part of your architecture, you should be comfortable enough with the technology to basicall

> It is properly documented? IMO If you're really staking a key part of your architecture, you should be comfortable enough with the technology to basically be able to document/maintain it yourself if you need to. Put another, if your understanding of the tool/stack depends on someone else making it accessible to you, either you have an unshakable trust in that someone else, or you're in for a wild ride. I'll concur sometimes you might not have a choice.

blindluke 5y ago
You're assuming someone places value on proper documentation because they need proper documentation to make it "accessible to you". That doesn't have to be the case. For me, lack of proper documentation constitutes a red flag, and says something very negative about the project. The question "Is it properly documented?" serves as a simple and convenient way to filter out projects that have a low chance of being mature enough to fit my needs.
- makeitdouble 5y ago
  > The question "Is it properly documented?" serves as a simple and convenient way to filter out projects I hear you, my point is there are dozens of other convenient questions you can ask to filter out projects. For me personally "Is it widely used in production" is a better one for instance.
  - blindluke 5y ago
    > my point is there are dozens of other convenient questions you can ask to filter out projects Absolutely. And I agree with you that "Is it widely used in production?" is a better filter. But that does not diminish the value of the filtering done by "Is it properly documented?". After all, it's not like we're limited in the number of criteria we can use to filter out bad projects.
maerF0x0 5y ago
> IMO If you're really staking a key part of your architecture, you should be comfortable enough with the technology to basically be able to document/maintain it yourself if you need to. Hmm. Not entirely sure I agree. To use an example, I find it much easier to read https://pkg.go.dev/encoding/json https://pkg.go.dev/encoding/json than the dozen or so files in https://github.com/golang/go/tree/master/src/encoding/json https://github.com/golang/go/tree/master/src/encoding/json Perhaps I'm misunderstanding your point.
- makeitdouble 5y ago
  Good documentation has different level of criticality depending on where you are on the "I use a closed library with no access to the source" down to "this library is just a stepping stone, we have full control and will modify it as needed" If you are on the completely blind side, documentation is your only window into how it works, and good documentation is non negotiable (you will take a slightly worse working library if it has way better documentation). In comparison if you adopt a library as a time saving move, and audit all of its code the same you would review your own code, good documentation is a nice to have, but won't be the make or break point of your decision. You'll chose the better working code even if its documentation is meh. I you are putting your fate into a specific stack or library, I hope it falls on the latter category than the former. On the two json libraries, I guess they both work decently, and the only criteria is which one feels better to use ?

blindluke 5y ago

You're assuming someone places value on proper documentation because they need proper documentation to make it "accessible to you". That doesn't have to be the case. For me, lack of proper documentation constitutes a red flag, and says something very negative about the project. The question "Is it properly documented?" serves as a simple and convenient way to filter out projects that have a low chance of being mature enough to fit my needs.

makeitdouble 5y ago
> The question "Is it properly documented?" serves as a simple and convenient way to filter out projects I hear you, my point is there are dozens of other convenient questions you can ask to filter out projects. For me personally "Is it widely used in production" is a better one for instance.
- blindluke 5y ago
  > my point is there are dozens of other convenient questions you can ask to filter out projects Absolutely. And I agree with you that "Is it widely used in production?" is a better filter. But that does not diminish the value of the filtering done by "Is it properly documented?". After all, it's not like we're limited in the number of criteria we can use to filter out bad projects.

maerF0x0 5y ago

> IMO If you're really staking a key part of your architecture, you should be comfortable enough with the technology to basically be able to document/maintain it yourself if you need to. Hmm. Not entirely sure I agree. To use an example, I find it much easier to read https://pkg.go.dev/encoding/json https://pkg.go.dev/encoding/json than the dozen or so files in https://github.com/golang/go/tree/master/src/encoding/json https://github.com/golang/go/tree/master/src/encoding/json Perhaps I'm misunderstanding your point.

makeitdouble 5y ago
Good documentation has different level of criticality depending on where you are on the "I use a closed library with no access to the source" down to "this library is just a stepping stone, we have full control and will modify it as needed" If you are on the completely blind side, documentation is your only window into how it works, and good documentation is non negotiable (you will take a slightly worse working library if it has way better documentation). In comparison if you adopt a library as a time saving move, and audit all of its code the same you would review your own code, good documentation is a nice to have, but won't be the make or break point of your decision. You'll chose the better working code even if its documentation is meh. I you are putting your fate into a specific stack or library, I hope it falls on the latter category than the former. On the two json libraries, I guess they both work decently, and the only criteria is which one feels better to use ?