-0.1 C
New York
Wednesday, February 14, 2024

Visualizing APIs with tree diagrams, partly generated with AI


by Tom Johnson on Feb 13, 2024

classes:
academics-and-practitioners

ai

api-doc

visual-communication

I lately visualized each a cloud and Java API by way of some complicated tree diagrams that confirmed the objects returned, with all of the element inherent within the guardian/little one relationships and constructions.

One of many main rules of immediate engineering is to interrupt complicated duties up into smaller ones. This precept has at the very least two functions:

  • Most AI chatbots can’t course of giant quantities of textual content
  • You’ll be able to extra exactly direct the output from smaller inputs

As I’ve been working with AI chatbots over the previous few weeks on a selected mission visualizing APIs with tree diagrams, I’ve actually come to see how essential these two rules are. I’ll elaborate extra on the main points of the immediate engineering strategies, however first, let me clarify the documentation context.

I made a decision to create some visible diagrams that describe the APIs I work with. This would possibly appear to be an odd process, however the state of affairs is that we’ve got a number of APIs (of various varieties — e.g., Java, cloud) with related knowledge, and companions struggled to navigate the reference docs to search out the information they wished to see. These APIs ship huge quantities of knowledge to customers in varied parent-child hierarchies.

I first began producing dot diagrams from proto information utilizing an inside utility. The utility was fairly cool however had two essential drawbacks: (1) the diagrams appeared like spaghetti with so many traces in every single place, and (2) the diagrams didn’t hyperlink to the reference docs.

To get a diagram with hyperlinks, I began creating tree diagrams. First, I used to be stunned to be taught that AI instruments can convert a piece of JSON right into a tree diagram. There appears to be some sort of logic in AI instruments that may convert JSON right into a tree diagram or a tree diagram into JSON, as in the event that they have been equal codecs much like Markdown and HTML.

For the Java API, I discovered that I might additionally convert the API’s construction right into a tree diagram as nicely, usually by simply pasting within the documentation for every class! This form of blew my thoughts. (It’s onerous to elucidate in additional element, and I’m not doing it justice right here, however every methodology will get sure objects, and people objects have attributes.)

I began with a easy tree and constructed out every node one after the other, usually simply pasting within the documentation. It labored greatest if I began out with the high-level construction after which requested the AI to broaden every node with extra particulars. This method looks as if one that might scale to many documentation eventualities.

I additionally needed to train the AI the precise tree diagram fashion I wished, and there have been errors alongside the way in which I needed to right and repair, however by and enormous the AI instruments made this process possible in ways in which I wouldn’t have tried in any other case.

I notice it’s onerous to get a way of the complexity of this process with out seeing the main points. Sadly, the documentation lives behind a firewall, so I can’t share it or go into extra particulars. However think about a tree diagram so giant and sophisticated that it’s important to scroll down for some time to see all of it, navigating round 10 subnodes with completely different ranges of nesting and guardian/little one logic.

Right here’s an instance of what it sort of appears like. This diagram has been jabberwockied and doesn’t mirror the precise construction both. My diagrams have been really about 10 occasions this huge.

root {} 
   ├─WonderWhizzleSnacker {}
   │  ├─FluffPrep []
   │  │  ├─PufTwiz {}
   │  │  │  ├─WhipFlavor {}
   │  │  │  │  ├─FlimEssence (string)
   │  │  │  │  │  └─SpinRefine (quantity) 
   │  │  │  │  └─SnigDust (boolean)
   │  │  │  └─GlimPolish {}
   │  │  │     ├─PixieShine (quantity) 
   │  │  │     └─FrumBuff (string) 
   │  │  ├─FluffDetangle []
   │  │  │   ├─BumbleFluffRetrieval (boolean) 
   │  │  │   └─WiggleSproutDisentanglement (string) 
   │  └─RootGet []
   │     ├─BumpExped {}
   │     │  ├─GinProv [] 
   │     │  │  ├─PogBake (quantity)
   │     │  │  └─FlibBrew (string) 
   │     │  └─SnorgNav {}
   │     │     ├─FlutRefuel (quantity) 
   │     │     └─HobEcho (boolean) 
   │     ├─RootSort (string) 
   │     └─FabPick {}
   │        ├─WhifOrch {}
   │        │   ├─BanLull [] 
   │        │   │  ├─HumpHarm (quantity) 
   │        │   │  └─FluffTease (string) 
   │        │   └─FlufUntang (boolean) 
   │        └─TwitGrove {}
   │           └─GrifDistract (quantity) 
   ├─WhizgigBuild {}
   │  ├─FidFrame []
   │  │  ├─SnurdJig {} 
   │  │  │  ├─FizWrang (string) 
   │  │  │  └─KlopAppease (boolean) 
   │  │  └─QuigWeld {}
   │  │     └─SnizRust (quantity) 
   │  ├─SpinSprock {} 
   │  │  ├─WhipTight (string) 
   │  │  └─WigCal (quantity) 
   │  └─FizPow {}
   │     ├─Sparkle (boolean) 
   │     ├─FizzMon {}
   │     │   └─BlipTrack (string) 
   │     └─DingPrevent {} 
   ├─OpWozzle {}      
   │  ├─KnobTune {}
   │  │  ├─SnarfCalc (quantity)  
   │  ├─PlinkStart []
   │  │  ├─GurgleInit {}
   │  └─FrobMon {}
   │     └─WhipAssure {}
   │        └─HogEquil {}
   ├─SnickersnapScrambler {}
   │  ├─JibberCrunch {}
   │  │  ├─KnizzlePop (quantity)
   │  │  └─WhiffleFuzz (boolean) 
   │  └─WiggleWarp []  
   │     ├─SplortFizzle (string)
   │     └─QuiggleSnap {}
   │         ├─SplinkTweak (quantity)
   └─WhiffleFlummox {}
      ├─SplootScrunch (string)
      ├─WhizzTwizzle {}
      │   └─FlarpStack (quantity)
      └─PoggleWiggle []
         ├─SnurdlePop (boolean)
         └─Jumboflap (string)

This identical tree diagram would possibly seem like this in JSON:

{
  "root": {
    "WonderWhizzleSnacker": {
      "FluffPrep": [
        {
          "PufTwiz": {
            "WhipFlavor": {
              "FlimEssence": "string",
              "SpinRefine": 123,
              "SnigDust": true
            },
            "GlimPolish": {
              "PixieShine": 456,
              "FrumBuff": "shiny string"
            }
          }
        },
        {
          "FluffDetangle": [
            true,
            "WiggleSproutDisentanglement"
          ]
        }
      ],
      "RootGet": [
        {
          "BumpExped": {
            "GinProv": [
              987,
              "FlibBrew"
            ],
            "SnorgNav": {
              "FlutRefuel": 654,
              "HobEcho": false
            }
          }
        },
        "RootSort",
        {
          "FabPick": {
            "WhifOrch": {
              "BanLull": [
                111,
                "FluffTease"
              ],
              "FlufUntang": false
            },
            "TwitGrove": {
              "GrifDistract": 321
            }
          }
        }
      ]
    },
    "WhizgigBuild": {
      "FidFrame": [
        {
          "SnurdJig": {
            "FizWrang": "fizzy string",
            "KlopAppease": true
          },
          "QuigWeld": {
            "SnizRust": 789
          }
        }
      ],
      "SpinSprock": {
        "WhipTight": "taut string",
        "WigCal": 555
      },
      "FizPow": {
        "Sparkle": false,
        "FizzMon": {
          "BlipTrack": "monitoring knowledge"
        },
        "DingPrevent": {}
      }
    },
    "OpWozzle": {
      "KnobTune": {
        "SnarfCalc": 999
      },
      "PlinkStart": [
        {
          "GurgleInit": {}
        }
      ],
      "FrobMon": {
        "WhipAssure": {
          "HogEquil": {}
        }
      }
    },
    "SnickersnapScrambler": {
      "JibberCrunch": {
        "KnizzlePop": 123,
        "WhiffleFuzz": true
      },
      "WiggleWarp": [
        "SplortFizzle",
        {
          "QuiggleSnap": {
            "SplinkTweak": 456
          }
        }
      ]
    },
    "WhiffleFlummox": {
      "SplootScrunch": "glooping sound",
      "WhizzTwizzle": {
        "FlarpStack": 789
      },
      "PoggleWiggle": [
        true,
        "Jumboflap"
      ]
    }
  }
}

I discover the tree diagrams so much simpler to visually eat than blocks of JSON. It’s onerous to see ranges of nesting and which objects are on the identical sibling degree.

Moreover, I additionally needed to characterize each JSON and Java (for various APIs) with an identical sufficient tree construction as to be intelligible.

Having completed this mission, it gave me an incredible perception into our APIs in ways in which I didn’t perceive beforehand. And mission managers liked it!

After I first confirmed it to the first PM, he instantly wished each aspect linked to the corresponding reference documentation. This meant including a whole lot of hyperlinks. For the cloud API, it was pretty simple to get the hyperlinks as a result of a lot of the documentation was on a single web page, and I simply wanted to discern the logic of the hyperlink paths.

For the Java API, nonetheless, the Javadoc was so much tougher to navigate, with many various pages (a separate URL for every mannequin within the API). I needed to examine the hyperlink patterns to determine the logic, however as soon as I did, I instructed the AI discern the hyperlink patterns from the tree diagram. Then I had the AI write out a listing of hyperlinks.

I’m being cursory right here and never going into an excessive amount of element. This mission consumed me for 2 stable weeks, and I had many failed makes an attempt and revised prompts and such earlier than I had success.

I couldn’t add a ton of HTML hyperlinks right into a tree diagram with out making it break traces all over and turn into unreadable. So I used Jinja scripting logic (accessible on our doc platform) to make use of variables. I created variables for every aspect after which added an embrace that pulled in all of the variables for every diagram.

I then realized that completely different diagrams repeated among the identical aspect names. To get round this, I had so as to add a scope to the variables so that every variable title wouldn’t collide with related variable names in different diagrams. I used AI to grasp variable scoping in Jinja.

These tree diagrams may not be one thing that applies to many individuals, however for my explicit state of affairs, the result is actually superior. I’m having a tricky time understanding why tree diagrams aren’t extra frequent in API documentation. They visualize complicated objects in ways in which I discover priceless.

No matter whether or not tree diagrams make sense in different eventualities, my essential level was to explain that method I took with AI right here. I used process decomposition to interrupt down a fancy mission into smaller duties. There have been most likely 50 smaller duties I did earlier than I completed the diagrams. That breakdown of complicated duties allowed me to make use of AI to attain the consequence.

About Tom Johnson

Tom Johnson

I am an API technical author based mostly within the Seattle space. On this weblog, I write about matters associated to technical writing and communication — akin to software program documentation, API documentation, AI, data structure, content material technique, writing processes, plain language, tech comm careers, and extra. Try my API documentation course in the event you’re searching for extra information about documenting APIs. Or see my posts on AI and AI course part for extra on the newest in AI and tech comm.

In case you’re a technical author and wish to carry on prime of the newest developments within the tech comm, you’ll want to subscribe to e-mail updates under. You can too be taught extra about me or contact me. Lastly, notice that the opinions I categorical on my weblog are my very own factors of view, not that of my employer.



Supply hyperlink

Related Articles

LEAVE A REPLY

Please enter your comment!
Please enter your name here

Latest Articles