3 ms·
Poor documentation can be as much an asset as a liability, depending on your perspective. - The more comprehensive your documentation, the easier it is for you
by cosmie 6y ago
Poor documentation can be as much an asset as a liability, depending on your perspective.
- The more comprehensive your documentation, the easier it is for your competition to get a complete read on your product and it's capabilities. Which makes it both easier for competitors to strategically outcompete you, as well as counterfeiters to more accurately counterfeit your chips.
- The more precise your documentation, the more stringent your customer's expectations become. Poor documentation can act as a form of liability insurance - if someone uses a feature and things get weird, you can claim their use is out of spec. Harder to weasel out if things are clearly documented.
- The more expansive your documentation, the less dependent your (potential) customers will be on actually talking to you when evaluating if your product is fit for their use. I could see this being a negative in this industry - Feature X may be fine to use, but introduce intermittent instability if used for extended periods of time simultaneously with Feature Y, which can be compensated for via Z but doing so shortens expected lifespan by 30%. Wargaming out every possible contingency ahead of time would both be extraordinarily expensive, and result in documentation that would overwhelm the people using it. But not doing so while providing otherwise expansive/comprehensive documentation may lead to a false sense of understanding from your customers such that they write you off when your product would have in fact been a good fit.
- A corollary to the above - poor documentation trains your (potential) customers to just reach out directly and have a conversation about it. Which provides the chance for you to truly evaluate their situation and provide a more considered response that takes into account their use/circumstances. Which can either be using the product they may be familiar with, or suggesting a different one that's more appropriate that they may not have thought of.
- Ditto the above for implementation. Directly supporting them during their implementation can be more effective than them relying on generic documentation, since you can provide more contextually relevant details/instructions/direction. Which cycles back to the second bullet above, where you have the opportunity to provide information that steers customers in the right direction, addressing potential issues preventatively rather than playing damage control if their use wasn't completely aligned with the documentation they blindly followed. You can also directly put the costs of this work against the customer, rather than eating it via the comprehensive wargaming scenarios mentioned above. Which sounds harsh, but is far more efficient for everyone involved. Customers with a cookie cutter use case get cheaper per unit prices since you didn't inflate the amount of QC and experimentation required to flesh out the documentation, and you didn't waste time and resources chasing down contingencies that were never actually applicable to any of your customers.
So it sucks for a subset of people - hobbyists who aren't direct customers in the first place, cash strapped hardware shops who can't pay for that support, and the engineers at BigCos who aren't willing to pay for that support. But can still be rationalized when you consider it's an absolute non-issue for their primary target market, while also indirectly benefiting everyone else via the lower unit costs afforded by this mentality/approach.
- mschuster91 6y agoAs someone who currently dabbles in pcb design as a hobbyist, oh yes indeed. It sucks so much - every tiny little thing has extensive datasheets: from extremely detailed specs over test and application circuit examples that actually work to bitfield docs for i2c registers. But the more intelligence a Thing has, the inversely worse the situation becomes: good luck finding, for example, datasheets for a USB controller for Intel HDA codecs (if anyone has a hint on these, email is in profile)... and it's outright impossible to find anything for more complex stuff like Thunderbolt controllers, much less CPU / GPU / SoC chips. The closest a hobbyist comes across to real performance beyond RPi is COMexpress, which is not an as open standard as many would like plus the connectors cost a fortune... And to top it off: even for components that have datasheets... these lack licensing information, which means it's technically illegal to put a pcb design based on them as open source. Seriously I'd appreciate it if our governments could do something about that situation. The creativity decent rules about datasheets could unleash...
- salawat 6y ago>while also indirectly benefiting everyone else via the lower unit costs afforded by this mentality/approach Except everything you mentioned above prevents new competition from ever getting a foothold to drive down prices. Everything you just described is. only good if your end goal is to be an immortal, indispensable fixture of the economy, and I'd even go so far as to say the practices you endorse as strategically sound are (or should be) explicitly considered examples of strategies which are anti-competitive, anti-consumer, and should entail strict liability with a punitive consequence for the company involved if they utilize those practices for the reasons you state as a cost for and any tragedy results from the opaque nature of their dealings with the public. Nothing short of undesirable results and wasted effort is inflicted on the rest of society; which at the end of the day is mired in the quest to efficiently allocate resources, and further the State of the Art and the frontiers of human knowledge. You'll get the same exact things you counted as benefits for doing things badly simply by being proactive in communication with clients. and reaping the fruits of consumer and investor goodwill. You'll discover new edge cases and directions for truly novel developments when your customer tries to use your thing and, darn it, I need something just like it but with X. Hardware can be far better characterized, and the ability of the public to identify "the right tool for the right job" greatly increased. With more goodwill comes greater leniency, more willingness to allocate capital for novel problems, and a much more accommodating environment when it comes to risk. It's the difference between being a long living parasite, and becoming a household name. A vampire may live forever, but eventually somebody is getting a Stake and some garlic. Start acting like you've got something to hide, and people will go out of their way to do away with you. Free everybody from being helpless to help themselves though? That gets songs, monuments, and a chapter in the history books about how awesome and pivotal you were. Goddamnit, don't you want to live forever?