|
Not if the product hasn't changed since the documentation was produced.
Real programmers use butterflies
|
|
|
|
|
The programmer by this point is burned out, and tells them to find someone else to document it. "Can we ship it?" Yes.
Or, "I program; I'm not a technical writer".
It was only in wine that he laid down no limit for himself, but he did not allow himself to be confused by it.
― Confucian Analects: Rules of Confucius about his food
|
|
|
|
|
I think my second calling may have been as a writer. I do okay at technical writing despite no formal training in it. I think my articles here have helped me hone it as well.
Real programmers use butterflies
|
|
|
|
|
I really don't like the technical writing, but it's one of those things I know I have to do, for myself and any other developers that come down the line to look at my code. I try to be as accurate as possible with out overloading on details, except embedded; you can never have enough details.
I absolutely loathe making user "how to's" and other like documentation.
|
|
|
|
|
While it's not appropriate necessarily for technical documents (though maybe it should be) I find that the more fun I make something to read, the more fun I have writing it.
Real programmers use butterflies
|
|
|
|
|
Modern management.
Product lifespan is so short that documentation is irrelevant to them - it'll never be used because the new product next week will be different. So move the coder resource to the new product when it looks like the old one works and get more value out of it. If the resource complains, fire it and get another ...
It's not as if the customers are going to buy more than one of 'em anyway and they won't find out there's no support until we've got their money.
"I have no idea what I did, but I'm taking full credit for it." - ThisOldTony
"Common sense is so rare these days, it should be classified as a super power" - Random T-shirt
AntiTwitter: @DalekDave is now a follower!
|
|
|
|
|
That's true and depressing. 
Real programmers use butterflies
|
|
|
|
|
AND TEST THE DOCUMENTATION!
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.
|
|
|
|
|
In my case it's hardware, which is actually kind of shocking, but all of this applies to software as well.
Real programmers use butterflies
|
|
|
|
|
Exactly so.
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"
|
|
|
|
|
What did you expect for 50 bucks? Documentation takes time, often more time, than the actual development and time is money.
|
|
|
|
|
I expect the hardware I purchase to be usable. It's literally not usable. You can't do anything with it.
You don't understand. There is no usable datasheet.
You can't program against the thing.
Imagine you had a C static library with no header and no docs.
That's what this is, basically.
I can buy any electronics components I want - even for pennies a piece, and they all have datasheets.
I expect more for $5
Real programmers use butterflies
modified 28-May-21 3:43am.
|
|
|
|
|
Get down with reverse engineering. It's like solving a satisfying puzzle when you manage to get something to work!
|
|
|
|
|
Trust me, I've been trying.
Real programmers use butterflies
|
|
|
|
|
You are lucky it were just $80.
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.
Good luck
|
|
|
|
|
Ouch! I don't envy you that 1700 euro experience.
ElectronProgrammer wrote: a product (hardware and/or software) without proper documentation is just trash.
Amen!
Real programmers use butterflies
|
|
|
|
|
I find equipment vendor SDKs to be the worst!
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.
Cheers,
Mike Fidler
"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.
|
|
|
|
|
You get what you pay for...
|
|
|
|
|
It's not like I bought cheap components. I paid retail for gadgets that were priced at about what they were worth, if they were usable, that is.
Real programmers use butterflies
|
|
|
|
|
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.
|
|
|
|
|
I don't really have that option as the ESP32 platform itself is Chinese in origin.
Real programmers use butterflies
|
|
|
|
|
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."
|
|
|
|
|
I'd be saying more than "hell" if I saw that!
|
|
|
|
|
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.
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
