Quality documentation requires Diátaxis

It was an eye opening day for me when I first learnt that there's a theory around how documentation should be organized. That grand unified theory of documentation is called Diátaxis . Diátaxis states that documentation belongs in one of 4 quadrants: Tutorials How To Guides Explanations Reference documentation They illustrate the idea using the following image: You'll see that the space of documentation was broken down along 2 axes: Personal State: Understanding or Executing Task state:  For Understanding: Theoretical vs Real-World  For Executing in the Real World: Processes (User Flows) vs Tasks (micro actions) The 2x2 breaks down as follows: Understanding a Theoretical Scenario: (What's my model of the world? How is this system solving it?) Architecture Explanations Architecture Diagrams Data Flow Diagrams Algorithms & Theory Design Docs Problem statement / Problem setting Understanding a Real-World Scenario: (Walk me through how I can solve a p

The day I met Whit Diffie (of the Diffie-Hellman crypto fame)

It was either December 11th or December 18th. It was a neighborhood party at Didi's place. Honored to meet a Turing Award winner. I was too tongue tied to say anything beyond platitudes though. Tons of respect for what he's achieved. 

public static is harmful. It has no home in modern programming.

In the modern era of software development, "public static" is a relic of a past age. It reflects a bygone era where the concepts of composition and dependency injection were not yet well understood. In the modern world of software, where we understand both of these concepts relatively well - it's important to know that public static has no future. Let's see why: 1. public static forces static coupling, breaks composition and dependency injection This one is fairly obvious - it's in the name. A call to a public static function typically looks like: void myCallingFunction() {   MyUtils.publicStaticFunction(args); } As we can see clearly, the call to the public static function is happening with a direct reference through the containing class. The calling function is tied down to using only the implementation in MyUtils. The caller may not choose another implementation even if the caller may be calling the code in a test environment ( brittle composition ). This  &quo

Use the Heilmeirs for Project Funding

I learnt about the Heilmeirs from Vijay Gill , an ex-SVP at Databricks (now an SVP at RapidAPI). He said that this was the fastest way to focus the discussion around project funding. I've found it to be useful - sharing this with you. The Heilmeirs Project funding is governed by this one-pager process: What are you trying to do? Articulate your objectives using absolutely no jargon. How is it done today, and what are the limits of current practice? What is new in your approach and why do you think it will be successful? Who cares? If you are successful, what difference will it make? What are the risks? How much will it cost? How long will it take? What are the mid-term and final “exams” to check for success?

The Effective Executive

  The Effective executive “An effective executive does not need to be a leader in the sense that the term is now most commonly used. Harry Truman did not have one ounce of charisma, for example, yet he was among the most effective chief executives in U.S. history. Similarly, some of the best business and nonprofit CEOs I’ve worked with over a 65-year consulting career were not stereotypical leaders. They were all over the map in terms of their personalities, attitudes, values, strengths, and weaknesses. They ranged from extroverted to nearly reclusive, from easygoing to controlling, from generous to parsimonious. What made them all effective is that they followed the same eight practices: They asked, ‘What needs to be done?’ They asked, ‘What is right for the enterprise?’ They developed action plans. They took responsibility for decisions. They took responsibility for communicating. They were focused on opportunities rather than problems. They ran productive meetings. They thought and

For Effective Meetings, leverage the Meeting Bill of Rights

Meetings become enormously important as a medium of work execution as people become more senior over time. I've seen that the quality of meetings vary from person to person and organization to organization. Over the years, I've found the following principles very useful to frame my approach to meetings. I'm sharing this with you - hope you find it useful as well. Cheers!   Adapted  from "The Secrets to Masterful Meetings" ( PDF ); How Jeff Bezos runs meetings . Your Meeting Bill of Rights Meeting Notice.You have the right to be informed about the purpose and proposed agenda for a meeting, verbally or in writing, at least twenty-four hours in advance of the meeting. Timely Start.You have the right to attend meetings that start on time. 3 minutes late: issue a reminder; 7 minutes late: meeting cancelled.  Right People .You have the right to have all major viewpoints critical to decision-making represented at the meeting. Conversely, If you're not useful to the m

Can white prevent checkmate?

I reached here as black. White to play - Qh5 was my last move. I had just sacked my bishop for 2 pawns to open up the king. Can white save checkmate? Full game: Nimzowitsch-Larsen Attack Fairly interesting in its own way: 1. b3 e5 2. Bb2 Nc6 3. Nf3 d6 4. e4 Nf6 5. Bb5 a6 6. Bxc6+ bxc6 7. Nc3 d5  8. exd5 cxd5 9. O-O Bg4  10. h3 Bh5 11. Qe2 e4 12. g4 Bxg4 13. hxg4 Nxg4 14. Nd4 Qh5 0-1