Your browser failed to load CSS style sheets. Your browser or web proxy might not support elliptic-curve TLS

Building network automation solutions

6 week online course

Start now!
back to overview

We Need Product Documentation, not just Glitzy Demos

Whenever a vendor approaches me touting the benefits of their new gizmo, they want to give me a product demo, or offer me access to online labs… and I always tell them I’m not interested until I see their design and configuration guides.

Here’s why I think you should take the same approach:

Architecture first, then implementation details

Playing with new gear is nice (and vendors know that, which explains their focus on online labs), but we should keep the end-goal in mind: is the gear useful in solving our problems?

To answer that question, you need to understand:

  • The problem you have (which might be the hardest part)
  • What problem the vendor claims to be solving and what problem they’re actually solving (if any);
  • The architecture of the solution, and its limitations;
  • How it works;
  • And finally how easy it is to configure and operate (which might be what you would get from the demo).

In other words, you need to understand the architectural framework of the solution before focusing on individual bits-and-pieces.

Too complex? Let me rephrase. You need to start here (as boring and depressing as it may look):


Source: pexels.com

… so that when you add the details you get this:


Source: stocksnap.io

… and not this:

Finally, do keep in mind that a product that doesn’t have proper documentation might not be suitable for production deployment (or maybe it’s just me).

Or should we look at the product first?

Does that mean that there's no value in demos and online labs? Not really. You might want to look at a product demo to quickly decide whether to consider the product or not before spending time figuring out what it is – with so many products out there, you can afford to skip one or two just because the UI sucks.

4 comments:

  1. Hi Ivan

    What a pitty that I cant add picture to the comments.
    Wanted to paste excellent drawing showing an essence of your post.

    Michal

    ReplyDelete
  2. Hi Ivan

    What a pitty that I cant add picture to the comments.
    Wanted to paste excellent drawing showing an essence of your post.

    Michal

    ReplyDelete
  3. I completely agree, documentation should not be a discovery process after the fact.

    ReplyDelete

You don't have to log in to post a comment, but please do provide your real name/URL. Anonymous comments might get deleted.

Sidebar