The day job has been interesting in the Chinese curse sense, largely due to a certain software juggernaut’s less than ideal approach to documenting its software. To put it simply (for values of simple that a mostly non-technical audience will understand), after spending the better part of two weeks trying to use the software to do something all the marketing says you can do, in a way that all the marketing and the help documents say you can do, yesterday was the day I discovered that yes, you can indeed do all these things, as long as you don’t try to do all of them in the same system.
This is rather like telling a writer that yes, you can use this wonderful piece of software to write your books and set them up for e-publishing, and monitor your sales, while neglecting to mention that the sales monitoring module doesn’t work if you have the novel-writing module enabled, and you need to subscribe to the online e-publishing service to use that part because it’s not supported in the standalone version. And never actually making this clear in any of the documentation.
Yes, software documentation (otherwise known as “those bloody useless excuses for Help files”) does – or should – have a purpose. Its purpose is communicate. What software documentation should communicate is such things as how the software should be used, what it doesn’t do, and what you should not attempt to make it do lest you open a portal to Dread Ry’leh and the gibbering eldritch horrors contained therein decide to make a little tour of Earth, collecting souls along the way. Yours will certainly be the first one on the list, unless you, like me by the end of the day, have become a gibbering eldritch horror and started a soul collection of your own.
On the plus side, the novel-in-progress is past 50,000 words and still going strong. I’m at the first tipping point, with All Hell about to break loose and the tension is winding up nicely. In a few thousand words at most, an extremely one-sided battle will start, and run across multiple threads for the rest of the piece. It’s going to be a long, difficult ride…
So here’s a recent slice, completely out of context, just for the fun of it.
By the time Zofija walked her from her cabin to the armory to have her environment suit fitted, Lida was beginning to be comfortable with controlling the cabin’s functions through her phone. The link between it and the com meant she could take calls with the phone through a familiar interface as long as both were close.
If she thought of it as Bluetooth on steroids, she could make sense of the arrangement.
Trying to match protocols like that must be a nightmare. Some of the coworkers who worked with the UN software had complained about that kind of thing, and they were working with the same basic assumptions. Zofija’s offhand comment that Prussian scientific mathematics used ssirrissian numeric notation – in either base 16 or base 4 – left her wondering how any human managed, especially since regular mathematics used the typical human forms.
Medicine using tiruler notation and binary or octal did not help. Lida barely remembered how mathematics with different bases worked: Prussian Technologists and Hospitalers routinely converted between all five mathematical systems. The consequences of misidentifying the math system in use was enough to send ice cascading down her spine.
Zofija only laughed. “That is why ssirrissians dominate our sciences, as Brothers or citizens, and why tiruler dominate the medicinal arts. They have been working there far longer than humans.” She gave Lida’s shoulder a gentle squeeze. “We make better fighters and we’re capable of being good at most anything with the right training.”
The encouragement helped give Lida the courage to walk into the armory as though she wasn’t terrified of whatever kind of training Ceslaus would be throwing at her.
He grinned at her, apparently seeing through the facade without trying. “Lady Lida, welcome. I feared you might not wish to return.”
She offered the Prussian style equal-to-equal bow. As she understood things, she outranked everyone here except Friedrich, but this was the Clothier’s realm, and as such, she was silently telling him she accepted his sovereignty here when she did this.
American customs were so much simpler. Assume everyone is your equal as a person, shake hands, call them by name unless they tell you otherwise. She’d never joined the military so she lacked the automatic recognition of rank used there.
“I cannot say I am looking forward to this, Lord Ceslaus.” She spoke in a dry tone, but with as much of a smile as she could manage. “It must be done, so best to have it done quickly and correctly, yes?” That was one of Oma’s sayings, complete with the oh-so-Germanic ja? at the end of the sentence.
“Indeed so, Lady.” Ceslaus spread his hands in a gesture of innocence that failed to achieve anything resembling innocence. Him having the weathered appearance of an old sergeant, complete with faded scars, and the build of a tank rather overwhelmed everything else. “I apologize in advance for any missteps: it has been a long time since I needed to work with someone entirely untrained.”
“Of course.” Lida could understand that: she’d been told by a few people now that all Prussians were taught basic combat as part of their schooling, so that if it came to the worst they could all fight effectively. With an ever-present threat like the Dracaener, they’d likely have the social unity they needed to keep people willing to subject themselves to military training and command – not that she hand any illusions that the Order’s leaders were above using propaganda and indoctrination to keep their population willing.
If there was one thing that overrode everything else she’d seen about Prussians, it was that they were willing to do whatever they had to and atone for it later.
The environment suit looked like light armor, and felt like a mix of synthetic fabric and some kind of ceramic. The stand made it look as though it was a set of overlapping pieces, something she soon found was far from the truth.
Ceslaus patiently guided her through clipping each piece on, starting from the boots – sabatons that wrapped around her boots and left no visible seam where they closed or where they hinged. Those connected to greaves to cover her lower legs, and those in turn to poleyns, then cuisses. Each time Lida added a new piece of the suit correctly, it left no visible seam or hinge. The fit was snug without being uncomfortable.
The explanation, that the components of the suit had evolved from the armor of the founding Knights and the names for each component had simply been carried on to the corresponding pieces of more modern armor, helped Lida to see the point of something that had so many pieces. Apparently it was easier and cheaper to make armor that interlocked seamlessly than to make a single large suit, even though a faulty connection meant a dead wearer.
Not that she expected to be dealing with hard vacuum, but it was better to have the protection than not, especially when it was also capable of resisting Dracaener weapons. Not concentrated fire, of course, but stray shots would have no impact.
Once her legs were covered, Ceslaus had Lida run through a series of flexibility exercises to ensure the suit didn’t impact mobility in any way, then brought her back to the stand for the next phase of learning to put the suit on.
If it’s not too painful, what precisely can you *not* do simultaneously, in which Certain Product from a Large Software Company? It might be a good thing for others to be forewarned of…
You can do anything you want, all at the same time… unless you can’t. Therein lies the problem.
Complex software systems are complex. They have failure states that arise only under unique circumstances, on particular hardware.
Like: Open Office seemed incapable of holding a novel-length text file. So I bought MS Word. But lately, Open Office holds large files just fine, on the same hardware. What changed? I don’t know. But something seems to have.
Interesting quirk I learned recently on MS Word. Sa you have a MilSF novel, and you haven’t added the last names, planets, etc. to the customized dictionary (So they all show as a spelling error). As you’re reading through, it pops up a window saying “there are too many spelling errors in this document to show.” And promptly cuts out the red spelling and blue grammar lines.
What version are you working in? I would have expected them all since Word2000 to handle a book’s worth of such.
2016 shows them all. Oh boy does it show them all.
The Word and Excel formats prior to 2007 had a lot of limitations, some of them based upon using 16 bit integers in the binary formats. The formats themselves are much less limited from 2007 onwards (they’re essentially XML + images, stored in ZIP format), though the applications themselves often have plenty of limitations – e.g. Excel can only properly handle filtering/sorting on 10,000 rows of data.
Oh, yes. That happens when the number of “incorrect” items According To The Deities Of Word exceeds the working memory of the system and starts to slow things down. I suspect an internal limit somewhere – I’ve hit it more than once with older versions, too.
Of course, I routinely give my computers some form of heart failure through memory stress. Right now I’ve got three browsers open. The one that’s got the least going on has 5 tabs open. This one has nearly 30.
Four separate browser instances, half a dozen tabs each. Two DOS emulator windows. Two console windows, two tabs each. Music player. GKrellM. Torrent host. Two word processor instances. Two virtual desktops. One VNC host. CPU load 8-10%, about 4GB RAM in use.
Modern software is rather porky.
Do you use the weather (GKrellWeather) plugin, and if so does it work for you? I do, or did, but it seems to have stopped working and now tells me it is +69F in a Minnesota Winter. And I have double checked that the AWOS callsign is correct.
I never got that or KWeather to work. Of course, the NOAA forecast – right down to my ZIP code – is usually so hilariously wrong that my wife calls it “that entertainment site.” (as in more than 20F wrong on temperature, and utterly failing to mention minor details like clusters of tornadoes ripping up nearby houses…)
It worked fine for me.. until the last few months. Not sure what changed. I saw one bug report with a fix, but I went to apply the fix and found it already there, so something else is amiss. I don’t expect it to forecast, but it’s nice to see the local AWOS readings with having to load a web page. Well, it was nice.
That would be because it’s far cheaper to throw hardware at the problem than the developer time to slim it down.
I used to overload Word and crash it by typing too fast. Apparently the laptop keyboard to Word interface was the choke point.
I stopped using Word when it ate 20,000-odd words of a WIP (not that it was good) back in 2003.
I break hardware so routinely by doing too much with the software on it my husband, who is a sysadmin, says I should go into testing. I think my kill count on hard drives, both laptop and desktop, is over ten now.
Meant to say Word ate the document when I pushed spellcheck.
I’ll check when I get home, but I think it’s called Word 360. The stupid online subscription one, that keeps asking me to save things to the cloud.
Office 365. Ugh. We’re transitioning to it at work. I spent hours writing test cases this week for confirming compatibility with various custom and commercial applications.
Microsoft named one product Office 365, but the other one Xbox 360.
Does that mean your Xbox is going to fail to work on five separate days per year?
It was jarring to hear people talk of their “360” rather than Xbox, as $HOUSEMATE used to work with IBM mainframes so I heard of the IBM 360 and OS/360 (and 370, and 390… and the Hercules emulator).
Users are infinitely capable of devising situations the programmers never thought of. I have a particular talent in that direction – which is handy when I’m breaking the company software as part of my job. Not so much when I want someone else’s Very Expensive Software to do *its* job.
Visual Studio, Team Foundation Server, and Load Tests. You can run load tests with all the fittings from your machine, but trying to push them to a *properly configured* setup to farm them out so all the requests are coming from multiple locations? Nope. Team Foundation Server says it can run them, but the hosted version won’t take data driven tests and the on-site one has yet to actually run one.
I’ve been cursing it for the last two weeks.
And yes, you asked.
That does sound like a real pain if you’re trying to conduct data-driven load testing.
TFS? You have my sincere sympathies. Is management* aware of hosting solutions like Gitlab? https://www.slant.co/versus/2482/634/~gitlab-ci_vs_team-foundation-server says that their survey respondents** VASTLY prefer GItlab to TFS.
* I assume this was a management decision, because if it were up to the coders, I’m sure Github, or Bitbucket (or Gitlab, or…) would have been chosen. Or it could be a result of corporate inertia, because TFS was the best choice years ago and it would cost too much to move.
** No idea how they were selected, so can’t rate validity of survey.
Management is allergic to spending more money – TFS comes with the MSDN subscription so it’s effectively “free”. Apart from the immense amount of time spent making the thing behave.
Ooooh, THAT one. 5+ years ago, so (I think) at least two versions – but I never got that to work either.
Now, at the time, I figured that it was the setups. If there were two machines in the company that were actually configured the same way, and with the same service packs applied, I would have been amazed.
It can apparently be done, but there are a gazillion little things that all have to be set exactly right. So far the phase of the moon hasn’t been mentioned as a requirement, but I wouldn’t be surprised.
Different thing, but a colleague once told me that we apparently needed virgin sacrifice to get the current project working. I distinctly remember looking at her and saying “Ah d**n, we’re sunk, then.”
Back in the late 90s, Evil Rob was a computer technician and salesperson at perhaps the only CompUSA in the nation with positive reviews. One of his tricks was building systems for folk based on what they wanted: “Okay, we’ll get the best video card, the best sound driver, the second-best RAM…” at which point the person would, confused, ask why not the best of whatever component it was. The answer was that, for some reason, it didn’t play well with the other components.
Computers are weird.
Yup. They are that. I have not-fond memories of installing one of those IOMEGA ZIP drives in the late 90s. I wound up having to reconfigure the innards of my computer because it would NOT accept the CD-ROM and the ZIP on the same bus. I had to make the CD-ROM a slave to my hard drive to get the computer to recognize everything.
Ancient times when there were two “extra” interrupts and three “extra” port addresses, so half of everything came hardwired to the same ones, because nobody else would be using them, of course.
And shorting plugs. And “auto-configuring” ISA cards, that changed IRQs and ports every time you rebooted.
TSRs and device drivers that didn’t play nice with others, or had to be loaded in specific, non-obvious others, and…
[the bad old days]
SCSI Terminating resistors, that may or may not be internal to the external hard drive you’re connecting.
That’s just evil.
Oh, the really fun days. Hardware? Software? Some of each? Writing device drivers for the one component that did not work with the latest OS version… (I stopped that after NT 4 – suppose I could have still done it with XP, but beginning with Vista, they really got screwy with their requirements.)
Add SCSI devices that were hardwired to sit at a specific address, which was usually #1 or #3.
Then there was Fast SCSI, Wide SCSI, SCSI-2, Parallel SCSI, and probably others after I dumped the last of my SCSI hardware into the trashcan and waved an enthusiastic goodbye to it all.
And Adaptec has been on my permanent “never ever buy” list for 25 years now…
“Hello, I just bought a $600 Adaptec SCSI controller, but it didn’t come with the device driver disk.”
“That’s a separate SKU, and the price is $150 plus shipping.”
(and, at the long distance rates of the day, that was a $25 phone call)
Fast Wide SCSI, Ultra SCSI, Ultra Wide SCSI, LVDS, and now SAS.
Relatively recently I ran into a weirdness where a system would work fine… on 3GB RAM or less, and fail in weird ways on more. An iommu bug that acted very much like IRQ conflicts. It was a… bastage to diagnosis and lead to some of my rather rare (nowadays) cussing at computers not running Windows.
Don’t forget Netware drivers when you had to hard code in the MAC address of the network card before compiling. Each driver would literally only work with the machine that card was in.
And then there;s the software vendors that don’t want to pay for proper documentation… (speaking as someone who has been paid to write the stuff) … or write it themselves and it is… less than useful.
Your notes on what that particular function does are not necessarily user documentation.
Never, ever let the developers write the documentation. (Or the testers – although it will be complete, the poor user will be afraid to touch their machine ever again…)
I was once horrified that a “tech writer” turned my notes into his manual almost unchanged. Fortunately for most installations the gadget either just worked or immediately failed in a useful way, telling the installer/operator what configuration it was really set for.
I’ve given detailed instructions on how something works and lists of gotchas to the tech writers, and had them turn it into good documentation. I think it’s the lists of gotchas they valued most.
“Oh, we’ll just set up a wiki and our users will write the documentation for us!”
“Hey Rocky, watch me pull a rabb…”
I am reminded of the WIndows 10 Anniversary Upgrade that could not be stopped, only delayed a bit. It destroyed all the data on my hard drive. I had a RAID backup system. It destroyed the file structure so I now have 1.8 million files in one directory. Fortunately I also back things up to DVD disks, and had done a complete backup recently. I seem to be missing one short story.
Ugh. On The Husband’s machine every time it has to reboot he has to unplug *every* USB device (even the keyboard and mouse) for it to work. Something about his USB drivers does not play nice with the Win10 anniversary upgrade.
My machine? No problems.
G. Harry Stine used one of the early weird editors. It was fairly user-unfriendly, even by the standards of the day.
One day he fumble-fingered something and last most of a novel he was working on. After that, he hit ‘save’ at every paragraph and backed up to floppy disk several times a day. He bragged he hadn’t lost a single byte of work since.
One evening I got a call from a mutual friend; Harry’s wife had come in and found him slumped over the keyboard, dead. She said the dialog box on the monitor was saying his file had been successfully saved to drive A:.
Good work habits will help you all your life. And maybe slightly beyond…
Oh yeah. It doesn’t take long for CTRL-S to become a habit.
That’s one thing I really like about Libre office: it has several visual indicators that tell you there’s stuff in the document you haven’t saved. Plus it works/functions kind of like Word did before they put in that damned ribbon thingy.
In the very early, early days of the Mac, there was Microsoft Multiplan, which was the spreadsheet before Excel. I had version 1.0. It had to wait until operations were complete before you could do anything else, because MS didn’t give a shit about the Mac’s architecture, and rolled its own. This was a pain because it would automatically recalculate all the time, and then you’d have to wait to save, etc. Version 1.1 introduced interruptability. So you could hit Save while it was still recalculating, and it would stop what it was doing and do what you said.
One day I had to rush to turn in my assignment for class, hit Command-S, then Command-Q. You guessed it. The quit command interrupted the save and corrupted my homework.
Back in the old days I’d borrow a Mac IIe from mum’s school and use an antique version of AppleWorks to write. AppleWorks in one 5.25″ drive, my file in the other.
Everything went well, I was saving regularly, then I got on a writing roll… and somebody pulled the plug. Literally pulled it out.
I think they heard me scream three suburbs over.
I worked on ClarisWorks 4 and 5…. I think I’ve told the story of why I hate Steve Jobs before.
Are you sure that wasn’t an Apple IIe? Macs never had 5.25″ floppies.
Apple IIe… Yeah. I tend to blur the two brand names together.