Thursday, March 11, 2021

2021-03-11 Thursday - Tom Johnson's guide for documening APIs

During some research this evening on the topic of API Developer Portal solutions - and in particular, solutions for hybrid cloud operational environments - I happened upon some excellent writing on the subject of documenting APIs by Tom Johnson - heartily recommended: 

Sunday, March 07, 2021

2021-03-07 Sunday - Technical Debt - and Vigor's Black Box Theory


Photo by Lespinas Xavier on Unsplash

The subject of information technology Technical Debt has been on my mind this past week.

For non-IT folks, Technical Debt accumulates...sometimes by actions...sometimes by inaction...or simply by choices made...or choices deferred. And, like monetary debt - it can accumulate "interest".

While things on the surface may appear fine - underneath, there can be growing instability - which might be likened to rot, or rust - that can threaten the integrity of a system.

 Technical Debt can also be likened to a Gordian Knot type problem - and as time goes by - becomes increasingly more entangled - as layers of changes are made - and as the number of dependencies grow.

It can arise from several possible sources (and quite often, from a combination of several at the same time). Usually, the sources of Technical Debt  can be traced to one or more of the following:

  • The lack of a proper architecture foundation
  • The lack of proper tooling 
  • The lack of proper solution components
  • The lack of continued/proper maintenance
  • The lack of skill/knowledge in the personnel engaged in the work to design/maintain a system
  • The lack of commitment and funding to perform ongoing maintenance/refurbishment

Technical Debt can have severe consequences:

  • Reduced system reliability, availability, scalability.
  • Significantly increased system complexity
  • Significantly increased system maintenance costs
  • Inability to respond with agility to changing requirements 
  • Customer dissatisfaction
  • System failure
  • Business failure

There are some notable parallels between the concept of Technical Debt - and in the world of sailing, John Vigor's Black Box Theory.

John is well known within the global sailing community:

"John is the author of 12 boating books and scores of articles in boating magazines on three continents, including Cruising World, Sail, and Good Old Boat. His career as a newspaperman spanned nearly 40 years in America, England, and South Africa. He has written more than 5,000 humor columns and more than 2,000 editorials for metro daily newspapers."

In an article in the July/August 1999 edition of Good Old Boat magazine, John describes his Black Box Theory - which he derived from a talk given by another sailor at the Durban Yacht Club, almost 30 years earlier. 

The speaker mentioned the four essentials for a successful  yacht voyage as:

  1. A well found-found ship
  2. A good crew 
  3. Adequate preparation and maintenance
  4. Seamanship

That speaker also referred to something that he called "The Fifth Essential" - but would not name it directly.

Over time, John noted a similar theme in the talks given by other world famous sailors (such as Bernard Moitessier, Jean Gau, and Eric Hiscock) - and he distilled the idea into his "Black Box Theory": 

",,,every boat possesses an imaginary black box, a sort of bank account in which points are kept. In times of emergency, when there is nothing more to be done in the way of sensible seamanship, the points from your black box can buy your way out of trouble. You have no control over how the points are spent, of course; they withdraw themselves when the time is appropriate. You do have control over how the points get into the box: you earn them. For every seamanlike act you perform, you get a point in the black box."


As I reflect on the innumerable systems around the world that suffer from growing levels of Technical Debt - I cannot help but wonder - how many points are left in their black boxes

And, as I work to prepare my own sailboat for future voyaging - I wonder - how many points are on deposit in my own vessel's black box?

photo by Kelvin D. Meeks

I'll leave you with a popular toast from the world of sailing:

"Fair Winds and Following Seas"

Additional suggested articles

Saturday, March 06, 2021

2021-03-06 Saturday - Book Review: Becoming a Salesforce Certified Technical Architect



This weekend I reviewed a new book.

Teny Thomas (Marketing Coordinator, Packt Publishing) graciously offered to provide me with a review copy of "Becoming a Salesforce Certified Technical Architect: Prepare for the review board by practicing example-led architectural strategies and best practices", by Tameem Bahri, Chief Technology Officer - Europe ( COE), with Capgemini.

My summary: Ambitious - Practical Coverage of the Application of Salesforce Architecture


Chapters include:

Chapter 1, Starting Your Journey as a CTA,

Chapter 2, Core Architectural Concepts – Data

Chapter 3, Core Architectural Concepts – Integration and Cryptography

Chapter 4, Core Architectural Concepts – Identity and Access Management

Chapter 5, Developing a Scalable System Architecture

Chapter 6, Formulating a Secure Architecture in Salesforce

Chapter 7, Designing a Scalable Salesforce Data Architecture

Chapter 8, Creating a Lean Solution Architecture

Chapter 9, Forging an Integrated Solution

 Chapter 10, Development Life Cycle and Deployment Planning

Chapter 11, Communicating and Socializing Your Solution

Chapter 12, Practice the Review Board – First Mock

Chapter 13, Present and Defend – First Mock

Chapter 14, Practice the Review Board – Second Mock

Chapter 15, Present and Defend – Second Mock

Appendix, Tips and Tricks, and the Way Forward


What I Liked:

I found this book to be worth the time invested to read it – as it served to deepen my understanding of several areas of concern for the architecture design of Salesforce solutions.

  1. The numerous architecture artifact examples.
  2. The robust and non-trivial scale of the problems defined by the scenarios (starting with Chapter-5…)
  3.  Chapter-2’s discussion of BASE vs. ACID:
    1. BASE (Basically Available, Soft State, Eventual consistency)
    2. ACID (Atomicity, Consistency, Isolation, and Durability)
  4. Chapter-5’s detailed discussion of the requirements and architecture considerations for the Packt United Builder (PUB) global property developer scenario.
  5.  Chapter-6’s detailed discussion from a Security Architect’s perspective – with the detailed requirements and security architecture considerations for the Packt Innovative Retailers (PIR) global digital retailer scenario.
  6. Chapter-7’s discussion of data architecture – and performance implications of LDVs on the solution design – and mitigation strategies – as part of the discussion of the data architecture considerations for the Packt Online Wizz (POZ) online shopping portal scenario.
  7. The seasoned voice of experience – in guiding the reader through trade-off analysis in considering, evaluating, and selecting solution options for the various areas of concern.
  8. Chapter-8’s use of the Packt Visiting Angels (PVA) scenario is a fine example of the writing expressing a strongly grounded mentoring-approach – that stresses the importance of understanding the business and technical requirements – and of documenting the architecture design and decisions.
  9. Chapter-10’s discussion of Center of Excellence (COE) and Design Authority
  10. Chapter-12’s 1st full mock – Packt Pioneer Auto (PPA) global car rental company scenario.
  11. Chapter-14’s 2nd full mock - Packt Lightning Utilities (PLU) European utility company scenario.
  12. Appendix lists of links to: suggested training and study groups; stories & lessons learned; blogs and training providers
  13. Regardless of whether you ever intend to take  the CTA exam – this book provides a broad coverage of architecture considerations – across a number of interesting scenarios – that will help the reader expand and elevate their knowledge of Salesforce solution architecture design.


Suggestions for Next Edition

  1. At 602 pages, I think the length could possibly be trimmed by ~15% - with a sharp editor’s eye toward tightening-up some of the writing.
  2. There is some repetitious phrasing that could be eliminated (or varied a bit).
  3. At the end of each chapter, the value of the book could be substantially strengthened by including citations to the Salesforce relevant documentation, articles, blog posts, conference proceedings, release notes, YouTube channel talks, etc. – to provide the reader with links to additional resources to develop a deeper understanding.
  4. Chapter-2 should include a link to:
  5. Suggest making Integration a stand-alone chapter. Perhaps combining Encryption and Cryptography into a Security Architecture chapter?
  6. Add a discussion in Chapter-10 to cover Salesforce capabilities for API Observability, Monitoring, Alerting
  7. The pixel-fidelity of some of the diagrams needs to be substantially improved – see Figure 4.2 and 14.10 for just two examples. Zooming in – and the fidelity of the diagram becomes blurry. 


2021-07-31 Update:

 You may also be interested in my review of a new Packt book published this week - that is a fine supplement to the book reviewed above:  Salesforce Data Architecture and Management



© 2001-2021 International Technology Ventures, Inc., All Rights Reserved.