{"id":108754,"date":"2023-09-12T07:01:47","date_gmt":"2023-09-12T14:01:47","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/oldnewthing\/?p=108754"},"modified":"2023-09-12T07:01:47","modified_gmt":"2023-09-12T14:01:47","slug":"20230912-00","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20230912-47\/?p=108754","title":{"rendered":"The odd cadence of narrative engineering design documents"},"content":{"rendered":"

Within Microsoft, it was popular for a while (maybe it’s still popular) to write narratives surrounding every proposed feature. Here’s an example:<\/p>\n

\n

Alex works as a developer for a company that makes widgets.<\/p>\n

The company plans to manufacture widgets that take advantage of feature Foo.<\/p>\n

Alex has read that the Windows Blorg service supports Foo and decides to explore the possibility of integrating the company’s widgets with the native Foo support in Windows.<\/p>\n

Alex has downloaded the Blorg SDK and plans to implement a prototype.<\/p>\n

Alex likes Windows because of the many widget-related services already available in the platform.<\/p>\n

Alex writes a function that takes a BlorgServiceRequest ticket and zondrizes the ticket in order to activate the Foo feature.<\/p>\n

This document introduces a new API for zondrizing BlorgServiceRequest tickets.<\/p>\n<\/blockquote>\n

It starts with Alex being this total n00b who downloads an SDK to learn more about this Blorg thing. And then suddenly Alex is this Blorg expert running around zondrizing tickets like a boss.<\/p>\n

At least the introduction didn’t finish with<\/p>\n

Alex is delighted that Windows makes it so easy to zondrize Blorg tickets for Foo.<\/p><\/blockquote>\n","protected":false},"excerpt":{"rendered":"

Following the rubric off a cliff.<\/p>\n","protected":false},"author":1069,"featured_media":111744,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[26],"class_list":["post-108754","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-other"],"acf":[],"blog_post_summary":"

Following the rubric off a cliff.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/108754","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/users\/1069"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/comments?post=108754"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/108754\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media\/111744"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media?parent=108754"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=108754"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=108754"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}