The Lounge is rated Safe For Work. If you're about to post something inappropriate for a shared office environment, then don't post it. No ads, no abuse, and no programming questions. Trolling, (political, climate, religious or whatever) will result in your account being removed.
I often have to consume 3rd party webservices. Sometimes the only documentation is the auto-generated WSDL, but at least that's in a consistent format. Too often the documentation includes typos (subtle ones, like case errors in a case-sensitive interface). Or it describes a field as "boolean" but doesn't say what value it expects (you try True, true, TRUE, 1, Y, yes ... eventually it turns out to be ON or OFF )
Or there's a "status" field but the documentation doesn't give the list of status values; or it lists the values but doesn't give their meanings.
Or it gives the URL for the test service but not the live one, or vice versa.
When your "product" is software, the documentation is part of the product. If people don't know how to use it, it's useless. (Microsoft, take note! ... [if only ])
When you release a new product, TESTING the documentation is therefore as vital as testing the software. If nothing else, get a user with zero knowledge of your product, give them the documentation and lock them in a room to check they can actually use ALL aspects of your software. If you change your product, change your documentation and RE-TEST it.
But documentation has long been seen as both difficult and 'not work' (ie not productive) and hence is often badly done or not done at all, and certainly never updated. (This applies to just about anything, hardware, software, your Tv, fridge etc).
Add to that that it is often done either by someone so familiar with the product that they document everything in intense detail, but without covering the basic things that someone who isn't familiar with the product needs to know. This happens with an awful lot of FOSS stuff (try making head or tail of the WEB2PY docs until you've spent a very long time working with the framework, or the Apache etc) but commercial stuff is often as bad.
Microsoft in particular are experts at this, producing incredibly detailed docs that are only useful if you already know at least what Microsoft calls a particular feature so you can find its docs; or they leave out the most simple things. As an example there are many T-SQL commands that can operate on one or more things at a time, and yet I defy you to find a single code example anywhere in the MS documents that demonstrate use on multiple items, hence you have to experiment to find the correct syntax.
Other firms, of course, use people not familiar with the product to do the documentation - done right this produces something actually useful, but in 99% of cases the docs are just random words, sometimes vaguely associated with the product.
Documentation is the necessary evil that usually gets rushed out upon product release and receives the lowest priority throughout the evolution of the product, especially if it is up to a developer to keep it updated.
"Go forth into the source" - Neal Morse
"Hope is contagious"
I once bought a DDR development FPGA board for €1700 from a major European manufacturer and could never get it to work. It came with closed source examples that seemed to work but no project I made ever worked.
I looked deeper into the documentation and the pins where the DDR was supposed to connect to the FPGA were wrong (I knew from other earlier tests of mine that some pins were connected to other peripherals like LEDs and a serial console) and even mentioned pins that did not exist in the FPGA that came soldered on the board.
I spent some more money hiring support from the manufacturer to complain and, after two weeks, they reluctantly sent me VHDL source code of a project that supposedly they used internally in the company to test the board.
The pins were all different from the documentation. And their source did not work either .
I tried to keep complaining but they just closed the issue as "Fixed" and stopped replying.
Eventually I found out, from another unfortunate guy somewhere a few countries over, that the DDR would never work because the board had the connections very poorly routed which added too much noise and transients, and the reason the company's closed source example worked was because it was clocked at 1/16 the normal speed of the DDR (unusable for my project).
Regarding your predicament, I try to avoid Chinese companies for gadgets because they rarely have documentation for anything and never give support. They rather have you quit your current gadget and buy another from them.
If it is just an integrated circuit they make documentation because they want to sell to other companies that make gadgets.
So you might be on your own unless you can find someone that is also working on a modification of those gadgets and could already reverse engineer them.
I think products without a functional documentation should not get approved by whomever certifies them because, for me, a product (hardware and/or software) without proper documentation is just trash.
Here I am working to enable the use of their products by my customers, and they supply documentation and code samples that are truly useless, even when they work.
You'd think they would want to make my life as productive as possible to sell more of their hardware.
It all boils down to what is valued by management. There are many examples of severe myopia when it comes to proper methodology, documentation, and QA.
"I intend to live forever - so far, so good." Steven Wright
"I almost had a psychic girlfriend but she left me before we met." Also Steven Wright
"I'm addicted to placebos. I could quit, but it wouldn't matter." Steven Wright yet again.
I have learned to avoid buying from manufacturers that don't speak my language. Getting any real help is a pain.
Several years back, I bought a batch of fanless mini-PCs from a Chinese manufacturer to run some digital display boards. (Someone else's pick, but yes, I signed off on it.) When they arrived, I couldn't do anything with them. The BIOS was not fully programmed on any of them. After almost two months of emailing and attempting to use the chat feature on their site (and a couple of international calls to their un-manned support line), I finally got a response from someone with a link to download all the BIOS files and driver files I would need to set the PCs up. It took 8 hours to download less than 20 Meg of files. I think the server must have been a PC under someone's desk with a dial-up internet connection.
I flashed the BIOS, installed Windows, installed the drivers, then set up and deployed my display boards. About one week after deployment, the video chips on all of them burned out. I opened the cases to find that there was a piece of foam (not the thermal transfer kind, more like thin packing foam) pressed between the heat sinks and the case.
I was left with fourteen PCs dead, two months wasted time and effort, and users calling me an idiot for deploying a bunch of new display boards that looked like a colorful lightning show superimposed over bug races just days after turning them on. It took a long time to live that one down and repair my reputation.
From now on, manufacturers have to have a support office in a country that speaks my language before I will buy anything from them.
Money makes the world go round ... but documentation moves the money.
Alert Text: Non-redundant:Sufficient Resources from Redundancy Degraded or Fully Redundant for Power Resource has deasserted.
Type of Alert: Warning - Redundant Power Supply
Getting these messages is always a stressful event. Only after logical/linguistic processing I concluded that probably all is well with our EsxI server. Can't they not just say: "Power has been restored. Have a nice day."
My mistake. This message was sent from our XServer (Lenovo) IMM system. EsxI is running on the system, but has nothing to do with this message. I can happily go on "remediate" EsxI and I will not deassert myself.
People fear what don't understand, hate what they are afraid of and destroy what they hate...
If something has a solution... Why do we have to worry about?. If it has no solution... For what reason do we have to worry about?
Help me to understand what I'm saying, and I'll explain it better to you
Rating helpful answers is nice, but saying thanks can be even nicer.
I put people that call for bans in the same group that call for "class action" lawsuits for everything. Most people don't realize that a class action suit lets the company pay a lot less overall, and only the primary plaintiff and the lawyers get any real payout. It costs a company a lot more to deal with thousands of "small claims" cases than one "class action" case.
In the case of people calling for bans, all they are doing is drumming up free advertising for the people they want banned.
Money makes the world go round ... but documentation moves the money.