DaedTech

Stories about Software

By

Add Custom Content to Your Documentation

Editorial note: I originally wrote this post for the SubMain blog.  You can check out the original here, at their site.  While you’re there, have a look at GhostDoc not only to help you with comment management and generation, but also to help you construct automated help documentation.

For the last several years, I’ve made more and more of my living via entrepreneurial pursuits.  I started my career as a software developer and then worked my way along that career path before leaving fulltime employment to do my own thing.  These days, I consult, but I also make training content, write books, and offer productized services.

When you start to sell things yourself, you come to appreciate the value of marketing.  As a techie, this feels a little weird to say, but here we are.  When you have something of value to offer, marketing helps you make interested parties aware of your offer.  I think you’d like this and find it worth your money, if you gave it a shot.

In pursuit of marketing, you can use all manner of techniques.  But today, I’ll focus on a subtle one that involves generating a good reputation with those who do buy your products.  I want to talk about making good documentation.

The Marketing Importance of Documentation

This probably seems an odd choice for a marketing discussion.  After all, most of us think of marketing as what we do before a purchase to convince customers to make that purchase.  But repeat business from customer loyalty counts for a lot.  Your loyal customers provide recurring revenue and, if they love their experience, they may evangelize for your brand.

Providing really great documentation makes an incredible difference for your product.  I say this because it can mean the difference between frustration and quick, easy wins for your user base.  And, from a marketing perspective, which do you think makes them more likely to evangelize?  Put yourself in their shoes.  Would you recommend something hard to figure out?

For a product with software developers as an end user, software documentation can really go a long way.  And with something like GhostDoc’s “build help documentation” feature, you can notch this victory quite easily.  But the fact that you can generate that documentation isn’t what I want to talk about today, specifically.

Instead, I want to talk about going the extra mile by customizing it.

Read More

By

Valuing Behaviors that Indicate Organizational Mediocrity

Hello!  Once again, I’m feeling pretty excited to be doing some actual free-form writing on the blog.  As best I can tell, I typically write an average of about 1,500 words per day.  And since many of those no longer go toward my (now draft complete) book, they can go toward other things.  For instance, sharing my thoughts on organizational mediocrity.

Over time, I’ve observed a growing list of organizations in action.  Usually, these heavily involve tech, or else I wouldn’t get a phone call.  But the actual purpose, shape and size of these places varies considerably.

All organizations tend to share some common ground, however.  For instance, at any kind of scale, they tend to form themselves into pyramids.  They also tend to make rules targeting their lowest common denominator.  But today I’d like to focus on a different, subtler commonality.

Organizations trend toward mediocrity by valuing apparently beneficial behaviors.  I’ll chalk these behaviors up as locally maximizing; they make tactical sense and create strategic messes.   Companies and society both value them in individuals.  But, counter-intuitively, encouraging them in your organization paves the road to hell with good intentions.

Read More

By

Preemptively Identifying Dead Seas

Today, I’m going to try to tie various strands of my life together into one lanyard of efficiency.  I haven’t done a reader question for a while, so I’ll change that today.  In this post, I’ll offer a terminology nod to dead seas, a now-defunct term that became one of my favorites.  The best context I can now offer lies here, in a post of mine, summarizing it.

A few months back, I made a post on NDepend called, “What to do When Your Colleague Creates Spaghetti Code.”  In this post, I described a caricature that I randomly named Bill, who you might recognize as sort of a quintessential expert beginner.  I subsequently received a reader question about this subject.

How can I tell if the company interviewing me has a “Bill?” (i.e. “How can I preemptively identify expert beginners?”)

Well, I’ll take a crack at that.

Expert Beginner Primordial Soup

I think that a meaningful examination of this question requires us to look at the conditions that give rise to such archetypes.  In the original series/book, I cover part of it.  The organization must draw sort of a neat little box around the techie group and then put an advanced beginner in charge.  From there, the concoction needs to simmer in a nicely insular environment, in which the budding expert beginner receives no real negative feedback, second guessing, or industry exposure.

But this assessment focuses entirely on the software development organization.  An ensconced expert beginner reigning over some miserable, backward fiefdom requires “the business” as an accomplice.  Simply put, it requires the operational laziness to allow your business to be ruled by an unaccountable “expert” operating with utter opacity.

Expert Beginner Hut

Imagine you started a pizza shop and hired a pizza chef to run the kitchen.  Then imagine that you completely delegated the cooking to the chef, as you should.  Life treats all of you well for a while and you develop some business.

But now complaints from customers start to come in about the taste and presentation of the pizza.  “My pizza was incredibly salty and all of the pepperoni was isolated to three slices!”  When you bring this problem to the chef, he tells you that such is life when it comes to making pizza—and, also, get out of the kitchen.  You don’t taste the pizzas coming out or look at them or launch any sort of investigation when his pizza chef assistants serially quit, muttering about his incompetence.  You just count the inbound trickles of revenue and assume that’s as good as it gets.

Read More

By

Happy Thanksgiving, 2016!

I won’t be doing the regularly scheduled Thursday night/Friday morning post this week.

For those of you not in the US, today is the national holiday Thanksgiving for us.  To those of you in the US, happy Thanksgiving!  To celebrate, please enjoy this drawing of a turkey.  The turkey was almost the national bird of the US, but we ate it and chose the eagle instead.

turkey

By

Chess TDD 15

Prompted by comments from a few people, I’ve decided to see if I like using Trello for keeping track of the TODOs instead of Excel. Also, learning from past feedback, I’ve defaulted Trello to being really big when recording so everything is legible, and I copied everything over from Excel. Hopefully I like it as I go, but please let me know if it’s more pleasing to view as compared with the Excel spreadsheet, if it matters to you one way or the other.

Also, a meta-note. I apologize for the time between posts in the series and for the lack of posting in general, but I’ve been traveling nonstop and am pretty much living out of hotels, meaning my life is one of 3G-ish wifi and sub-optimal setups. Luckily, I’m driving everywhere and lugging my boom mic, desktop and monitors with me so I can still record in the hotel. 🙂

Here’s what I accomplish in this clip:

  • Make the “blocked” algorithm for horizontal/vertical less dumb.
  • Start the implementation for “blocked” diagonal.
  • Inadvertently create a potential solution for the problem of knight’s oddball movement.

Here are lessons to take away:

  • Even little things matter when it comes to readability.  For instance, at 0:40 I noticed that my test class name ended in should but the methods started with “returns.”  So, I took the time to fix this.  My advice is to get in the habit of avoiding sloppiness and inattention to detail at any level of code.
  • Bear in mind that changing prod code is fine while green in TDD, provided you’re not looking to introduce new behaviors.  It’s a refactoring if your goal is continue satisfying existing test cases in a different way.
  • A little before 10:00, I refactored a bit of a test while red for the sake of readability.  I shouldn’t have.  My bad.  Lesson is, no matter how much TDD you do, sometimes you flub it.
  • Sometimes a great way to get things passing when the implementation is getting hairy is to tease out a conditional that only applies to your new case and do something obtuse.  Use with discretion because it can lead you into blind alleys and cause problems, but there are times when getting to green can provide an aha! moment.
  • You’ll notice I refactored to a different method signature, changed some stuff around, and then refactored back.  This kind of waffling is fine.  With TDD, you’ll get used to fearlessly refactoring and slinging stuff around until you settle on something you like (or at least thing is the least bad, for now).
  • Get it working ugly now, make it pretty later.  It’s sometimes amazing how an algorithm will suddenly make itself obvious after a bit of brute forcing and futzing around.