Is Anyone Writing Documentation Anymore?

So the last exercise I had done before Hurricane Irma hit was to take a computer and completely install a new operating system onto it.

I will be doing that again today, from my own instructions.

 

Sure, it’s a bit esoteric, some people are good at reading between the lines.

 

The problem with that is that you end up spinning your wheels and finding that something you assumed, you assumed wrong.

 

For the record, when I write documentation, I write it as I do it. That way I know it actually works.

 

It may have taken 26 steps once you had all the pieces, but if you had my hardware and the right software, you’d have a nice happy laptop running Debian. Thinkpad Laptop, X201 or fairly similar, although the version of Debian I used (Non-Free) was fairly liberal with getting what you need for many more laptops. Evil Wifi Drivers not withstanding.

 

The next step was to find documentation to install a web server.

 

The trick with installing complex software these days is that you basically have to find the right documentation. Or to be more precise, the correct documentation. Documentation that is complete and actually will work.

 

Oh and of course you personally have to read and understand what you are reading. No distractions allowed.

 

However, it is rare that you will find exactly the right documentation to do what you want. Often software is updated and that documentation you used two years ago to do that exact thing no longer works.

 

Highly common in the open source world, some very minor tweak will change where the files are and you are back online doing a search for what you were looking for.

 

In the consumer software world, you have a similar situation where the documentation was only partially updated since it was originally released. Think Windows XP vs Windows 8.1 vs Window 10. Things just moved around drastically within Windows itself let alone functionality.

 

I got “caught short” with trying to install a web server. Did it before. No problem. Since it is an open source project, you get what you pay for sometimes. Following the wrong guide I got the entire web server working. I just don’t have any passwords for anything.

 

As they say on a football field: Drop Back 5 and Kick.

 

That would be American Football. I never played Soccer, at least not for any length of time. All that running around annoyed me.

 

So at some point I’ll re-attempt that mess. FInd another tutorial that promises to install the LAMP stack and write down what I did.

Or I will find that one bug and fix it all. My choice, after all.

 

That is why I keep this blog. Many times I need to do something more than once. Create a Linux Web Server, save it off, then reproduce the results on a different computer a year later.

 

So when I post a long diatribe on how to do this and the other thing, I’m doing it for Future Me. So I don’t end up banging my head on a wall.

 

Like Today. I got it wrong. Happens. Time to start over.

 

For now, I’ll just go look for the football. Maybe the dog will chase it around the yard. Blow off some steam. Finish my Spanish for the day.

Try, Try again.

Advertisements

A Housefull Of Windows Replaced In Two Days

We’re beat.

26 windows down, 1 to go – if I got my count right.

Part of living in South Florida is accepting the environment and preparing for it.  Oh, sure, you do the same in other parts of the country.  Actually you do it everywhere, but you generally don’t give it all that much thought.

When you move in, set down roots in a new place, you begin that process that you learned when you were growing up – but didn’t realize it.  You adapted to your environment, and bent what you could to fit it to your own preferences.

We’re doing that here.

The house was built some time after 1956.  We aren’t completely sure whether it was 1956 or 1968.

Neither is the City.  Records are a bit sketchy.

We do know that nobody did any major renovations here.   A pool was added in the early 1960s, or maybe the 1950s, there isn’t a record of that either.

Someone laid tile in the “Public Areas” of the house.  Right on top of the grey travertine, or what ever it is called.  You could correct me and an hour later I’d get it wrong anyway.  One of those names I can’t keep in my head.

Just like most names.  They just don’t “stick”.

It was actually laid by most of the Police force of the City at the time.  They did a crappy job, just like anyone you’d expect to be drafted to do something by their boss.  Some of the tiles have a hollow sound to them when you step on them, and the grout is crumbling.

Another project for the future.

But past that, the cabinets were put in and left alone, just as most of the rest of the bones of this place.  We’re replacing some fairly major systems here as time goes on.

The first thing to go was the fire hazard of the electrical panel.  Do yourself a favor – find your electrical panel and see if you have the words “Federal Pacific Electric” on it or the initials “FPE”.  If you do, you had better replace it.  Major design flaws resulting in fires.  Such a bad design that the company was bankrupted and stripped for parts.  They actually cheated on the “UL” tests and got the approval they were looking for then sold the hell out of those faulty Stabloc circuit breakers.  Go check, I’ll wait!

But the windows remained.  Leaky Jalousie windows.

Not. Any. More.

Impact resistant windows.  The words “Impact Rating: Large Missile” are written on that sticker on the windows and are waiting for the inspector. 

I won’t test that although I did get a chuckle out of the phrase.

Much quieter too.  I’d say it knocked the noise level down outside to where I can’t hear the cars on the street and I’m hearing different sounds from inside the house.

I may have to let some of the old style mechanical clocks stop because they’re now so prominent when the radio or TV is off.

The sounds changed so much that now Rack is alerting to different things.  He actually “moofed” at the ice maker until he got told it was OK and got used to it.

It was 2 solid days of construction.  Knock out 27 windows, replace with 18 or so, and then caulk everything.  New woodwork.  Stucco where needed.

Oh and lets not forget that while all that is going on, the house is effectively without windows.  No, not “open windows” but “missing”.  Letting in a Mosquito is not an option.  Letting in 50 mosquitoes was what happened. 

And “Letting In” is not exactly correct so much as they let themselves in.

We have a thing that looks like a tennis racket.  It has a set of parallel wires and when you swing it through the air, it will zap any bug it hits into a vapor with a white hot flash and a “SNAP!” sound.

Rack hates it.

But it works.  When the first day of demolition and construction was finished and we were sitting in the chair, one swipe through the air killed 21 mosquitoes.

At One Pass.

Inside the living room.

The next morning I killed one on each arm before construction began anew.

I’m a quart low at this point and the top part of my brain is drying out from the donation.

But it is mostly done.  One window left and we’re done.

What.  A.  Weekend.

*WHEW!*

Dice.com Latest Upgrade Broke The Site

At least as of 6AM to 9AM, the job search website for tech, www.dice.com is not useable in my experience.

They went ahead and rolled out a major revision of their website today.  There actually were a few things in it that were kind of slick.

When you go in to do a search for a position, and it makes sense to do so, you have a slider for a criterion.

For example, when you are requesting a page for a search, you can tailor the number of results you want back by using a slider to change the number from 10 to 100 in increments.   The 100 is a big help.

Distance works the same way.

There are a few others, but the problem is that there should be a little box at the end for you to enter in a specific number.

Why? 

Simple – I live in Wilton Manors, Florida.  I used to have a search that would look for a 27 mile radius.  That would include West Palm Beach but specifically exclude downtown Miami.  I don’t want that commute, nor would I want that for anyone else. 

If there is a slider, you need to be able to enter in a specific number.

They also deleted the ability to search for an Area Code or a group of Area Codes.  Broward County is 954 and 754.  Palm Beach County is 561.  Having the ability in a large urbanized area like this to simply search for something within a county is very helpful.  Otherwise, the distance must be used, and will slow one down with extra searches.

They deleted the ability to exclude recruiters.  Recruiters in my experience are unreliable.  I tend to look for direct hire only.

They clearly did not test their site when they went “Live” today – by the time I got to it.  It may be fixed later, even later today.  Much of this could simply be because they are rolling out changes at this moment.

When I get the results of a search, they come back with either “Relevant” or “Date” available, but the default is usually Relevant unless you caught the tick box and set it.  But the link is dead to change it back – normally, but not always.  This sort of inconsistency is very common within the site.

That’s the problem.  Things work sometimes but not always.

So basically their site is not useable as of this writing, 9:15 AM EST, 12/15/2014.

As for the way it looks? 

I personally am not a fan of the Web 2.0 Look And Feel for things where there are a lot of items to search. 

Dice.com is one of those sites.  They are presenting a database of links and a tight list format is the most useable. 

I understand that they want to look different than the other two big sites, www.Monster.com and Careerbuilder.com however, their search results in LARGE FONTS and lots of Whitespace means that you’re constantly paging when you do get the 100 results per page, if you can actually get things to work.

Thank you again for the 100, it helps.

But when you page through the site on a large monitor (1920×1080) getting only seven results per view until you page down is limiting.  Put as much on a line as possible.  I guess that means it’s first page with 4 links, then 13 pages of 7 links (or so) plus the remaining 5 links (or so) – that’s how the math works out.

Your User Interface guy must have missed that particular meeting.  The Testing folk are confused too – I got a page coming up using the old interface and immediately thought “THANK YOU!”. 

Then I refreshed the page and it was back to the new design.  There were no links though, kind of a surprise since I saw links on the Old Format Page.

I’ll be waiting.  The new design needs A LOT OF WORK.  The site has so many bugs in it that I simply closed every window that I had.   All my old links are no longer functional.  If I try to recreate them, the site is so buggy that I can not get anything even remotely like the results I expect.  I can’t page to the second 100 results.  Not even the old text search works properly.  If you want to search for Business Analyst, and put them in quotes, the new software thinks you are looking for “Business OR Analyst”.  It’s not the same thing.

For example, if I search for anything within 20 miles of zip code 33301 I am showing results in California.  California is a great place but a bit more than 20 miles away from South Florida.

Oh and one missing thing that is extremely important.  Dice removed the number of hits that a particular resume has.  It’s a metric that needs to return.  How else would you know if your resume is effective unless you know now many people look at it in a given month?

At this point, there’s nothing else that I could suggest other than telling someone who wants to use a job search engine to wait this one out and hit the other sites.  Dice.com is unusable due to UI, UX, and QA issues today.  

They tried, but … well, maybe tomorrow.  They went with a Big Bang Release and broke what they had before.  Would be best to roll it all back and try an Agile Project Management approach of gradual improvements instead of what they got here.

Monster.com, Are You Kidding? Fancybox? Really?

In business, there is a phrase.

“Eat Your Own Dog Food.”

Monster.com doesn’t seem to realize this in their roll out of new “features”.

You see, Eat Your Own Dog Food really means that you’re going to use your own product to make sure that it suits what you intend it to do, and that you aren’t giving the competitors an unfair advantage.

In web development and Project Management, this means finding someone who becomes the “Subject Matter Expert” and “Product Owner” and takes on a very special role.   When I worked at the university, and in every position I have held back into the beginning days of my career, I’ve assumed this role.  It means that you are going to step back, listen to what the “Main User” of the system says about it, and champion that role within “Development” so that the Main User’s need are best served.

It means that you have to anticipate how any person will use the system and make sure that problems do not occur, and that when they do, problems are dealt with gently and “Gracefully”.

It also means that unintended consequences sometimes occur like in this picture above.

It is one of my least favorite features, the “Fancybox” or the “Lightbox”.

It is also very very rarely used correctly.

This is an example of how badly monster.com used the fancybox.

I did this under “my signon” and on another browser with no signon and it repeats itself.

Simply put, go onto Monster.com and do a search for any position you like in what ever zipcode you prefer.  Monster will return a list of positions.  It may even give you more than one page.  When you go from page 1 to page 2, it will put a “fancybox” up on your browser asking you “Let These Jobs Come To You”.

No, you blistering idiot, that is not what I wanted.

You see it will do that for this page, and any future page I want to look at. 

Every Blistering Page.

Ok, so I’m quoting the TV Sliders and Dr. Arturo with his wonderful rants and insults, but the point is still valid – Fancyboxes rarely serve a useful purpose For The User.

I went in immediately to my browser, clicked “Adblock Plus” and found a script.  I blocked it, and refreshed the page, and now I’m back to the old Fancybox Free behavior.

If I wanted an RSS Feed of the search parameters, it would not work because since I live in a major metropolitan area, Miami-Fort Lauderdale-West Palm Beach, there are thousands of jobs.  I have given up on RSS Feeds for this because they “max out” at 50.  I typically would need around 500 to be able to see the last two days worth of positions on this given search.

I have many searches, and have saved each individual page to save me a LOT of time that would be otherwise wasted clicking on “Next Page” buttons.   If I were not able to do the search the way I do, then I probably would have stopped using Monster.com a long time ago.

So all you need to do is go into your adblock plus and block the script called:

http://media.newjobs.com/nmy/usen/iperceptions506.js

It is badly written code, your QA, Development Department, and Project Managers have made a mistake.

It simply does not belong in a professional product like we have come to expect in Monster.com.  It only can have come from someone who has sat in too many Marketing Meetings and thought they could get more “buy-in” from their users.

Web Annoyances – Websites Where Keyboards Don’t Work

This one gets me a lot.  
It’s so basic that I have to wonder who on earth is making these web pages? 
Worse, who on earth is approving and testing them?

Oh, that’s right, you can’t do Proper QA any more since everything is written overseas on the cheap.

You get what you pay for.

Rant aside…

For the most part, even now, the place most people are doing their “heavy duty” web surfing is on a browser.  I’m basing that on this blog’s statistics, and I feel confident that that feeling is backed up by most web services.

The proportion is roughly evenly split between Internet Explorer, Firefox (and its variants), and Chrome.

I personally have noticed this on Firefox and on Internet Explorer, on Windows, Linux, and on Mac OSX.

It just doesn’t happen on a tablet or a phone since the way you use a webpage is different there.  You only have a mouse (touchscreen), you rarely have a keyboard.

I notice this on a daily basis on Monster.com, but it also shows up with many other oddball sites.

Here’s how to find the problem on Monster:

  • Surf Monster and do a search.  Doesn’t really matter what kind of job you search for, your own zip code will be fine.
  • You will be presented with a list.  Pick one from the list.   It doesn’t really matter which.
  • Now that you are looking at a page, a job really, use your Page Up or Page Down keys.

They don’t work.

You actually have to click inside the body of the page to get the page to move.   You can tab around, cursor around, whatever you choose, but it just doesn’t work until you click inside the page.

If you are a web developer and call this done, you are bad and you should feel bad.

Zoidberg doesn’t like you and neither do I.

This also works with the Windows or Linux alternate page down, the space bar.  

Navigation is simply locked down until you click inside the page.

My best guess is that it’s a function of working with the software behind the scenes (Ajax) and having reworked your browser so that all the keys are forced to do a certain special task.  Don’t know but it’s still wrong.

Now go back and fix your web page.  That’s a rookie mistake.  If you’re good, Robot Santa may leave you a gift.

Too Many Cooks Spoil the Project

So how many times have you heard that phrase?

“Too Many Cooks Spoil the Broth”.

I usually start my own variant of it when I’m in the kitchen.

“Git!  My Kitchen!  MINE!”

People being social beings tend to gravitate where others are.   Prepare food and now you have cause and effect. 

Throw in a dog or a parrot or both and now you have a very full stew pot.

No, I’m not suggesting that you cook your faithful companion, feathered or furry.

When I’m in the kitchen puttering about, there’s a much higher chance that I’ll be joined by one of three critters in my house at least for a sniff around.

Usually the largest of the critters will mutter an apology and try to be scarce, or at least as scarce as possible.  The other two will either shout out a cheery Hello! or sniff a wet black nose around the corner while twisting his spine into a neat S Curve and sprawling in the entryway in the most inconvenient way possible.

Does that extra “help” speed up the task?  Nope. 

Trying to make a holiday meal doesn’t work when you have a house full of cooks unless they all have their tasks laid out in front of them ahead of time.

Making bread does not take two people.  However when the second person arrives, it’s always best to “give them a job” and ask them to go fetch something.

That’s why the midwife on TV programs will tell the “expectant Father” to go boil water.  Giving birth rarely requires boiling water, and it will remove an extra pair of hands while that pot is boiling. 

Go make us a spot of tea, pop, you’re in the way.

Recently I’ve found out that mindset has a formal name to it in Project Management.  It is called “Brooks’ Law”.

Fred Brooks was a person who managed large software projects for IBM back-in-the-day.  His observation was that throwing new people at a project didn’t make it finish faster, it would simply slow it down.  Reason is that you have to bring the new people up to speed first and that slows down your most productive workers.

To Quote:  Adding manpower to a late software project makes it later.

Too many cooks again.

Once they’re up to speed, you have all those extra “interactions” forming a bit of drag on the system and slowing everything down.

If it did indeed speed things up, that extra body, it means you didn’t have enough hands to get the job done when you started so sometimes … you just might have to throw people at it.

Just not when you’re baking bread.  If I’m cooking, I’ll tell you “Git!  My Kitchen”.

You’ll get your rolls later when they’re done, sorry.  Here, have a glass of Iced Tea.

The corollary to Brooks’ Law is even more telling.  Just don’t boil that water because:

“Nine Women Can’t Make a Baby in One Month.”

I’ll have that Iced Tea now. 

Inertia, or Resistance to Change

Objects in motion tend to stay in motion.
Objects at rest tend to stay at rest.

Newton’s First Law of Motion.

Sure, a marble on the table given a nudge will roll but it will also slow down.  The reason is the force applied to it from outside of the “system” of the marble and table.   It’s called friction.

That is a basic principle of Physics, but it also applies to life.

Some people are much better with change, they can apply themselves and work through things as if it is water off of a duck’s back.  Others are much more conservative and freak out when there’s the slightest bit of a wrinkle on that double oxford broad cloth shirt.

Instead of grabbing an iron, those folks will wring their hands and fret.

The point is that while things can be done, they almost always can be done more ways than one.  Toss the shirt out and buy new.  Of course that new one will still need to be ironed, but don’t say anything until they get that home from the mall.

There’s always a judgment call that has to be made as well.  How much effort needs to be applied to cause the change to happen?  Can we live with the results if we do or don’t change things?

If you keep asking questions like that you eventually end up with a tree of yes/no answers and build a process.  Things tend to sort themselves out in order.   If you don’t proceed in order you will end up revisiting things later, usually caused by a resistance to change, a rigidity of thought.

Can you take things in one big bite or can you divide and conquer?

All binary questions.  Yes, or No?

That would be the basis for a systemic analysis of a project.   Laying out all the alternatives, in order, and following the path of least resistance.

Oversimplified, but that is the meaning of “basis”.

Of course there are shades of grey, but they are usually held back for a later time. Especially if there are 50 of them, and that is a very different story indeed.