RESTful API Review meeting letter

This is a modified letter for showcasing.  It is not a direct replica of real internal letter, all names had been de-identificated to protect privacy and client corporate data usage.

This is a review letter before a micro service (Wallet 1.2.8) documentation went public

A PDF version sample will be provided in this Link soon. You will see the ToC (table of content) used on top of the letter. It's not shown in this blogger web page version. ToC is also a standard layout when I wrote in Confluence. It makes reading and navigating in web-based digital user manual easier.

Those are essential detail to apply in modern technical writing.

==//==

Hi Backend Team:

This is the preview doc for wallet 1.2.8. Although it has gone live since Jan 26, 2022, I want to show the team how we can deliver docs and product seamlessly with our coherent review. It's in private mode(red padlock) now before it's published. But I wish the team to know its existence and only certain people can work on it before it's published.

For each service, such preview content will be available only for:

  1. Team Lead (in this case, it's C*****)
  2. Developers (this specific service owner. In this case, it is K**) 
  3. Technical writer (in this case, it's Howard Wu from BnosK --- for now)
  4. PM, or PO of this service
  5. QA of this service


before it's officially released. 

Fig. 1 Restriction Setting for your team

I made some enhancements for the doc this time, those are:

    Changes notes at top
    RoC (Rate of change) is introduced
    Bold the new enum and parameters in each model
    Add models for all api by default
    Red (new!) letter for indication each newly added api
    Related tickets will be added to where it's mentioned


Changes notes at top


All the news for this version will be shown here. It gives quick orientation for what a reader is expected to check in this long doc.

Figure 2. Changes notes will be shown at top of user manual


RoC (Rate of change) is introduced


This is a rough metric to see how many api got deprecated or added in each controller --- when comparing with its previous version of Service. Since I can not receive the forecast for the planned features in next release, I can not make doc delivered right when the service goes live. Such metric is useful to gauge if the overall design for this service is starting to get out off track. If the RoC is huge, that means the design changes radically, in other words, (oftentimes it's getting) not good and not stable.

Figure 3. RoC shows how much was changed comparing to previous version of api release

As you can see, the Transfer Limit Controller is all gone, but there's no related info in jira tickets about why.

You may wonder why Wallet Controller has two RoC (-23.8% and +14.3%), and how well this metric is when gauging a service design credibility.

The formula for RoC goes:

[(B-A)/A ]*100

I will have a post to explain that in my company-internal blog, correct me if I am wrong--- I am really glad to hear and learn from mistakes.


Bold the new enum and parameters in each model


I highlighted (bold) where the diff. are between this version and its previous one. This makes the changes clear to both users and developers.

Figure 4. new options are bold


Add models for all api by default


There were only examples for each request and response. Developers can not see all the enum in certain fields of response. Models are different from the examples provided. They specify the $int32 or $int64, sometimes showing all the available status enum for the api. In the original response examples, only one possibility can be shown.

Figure 5. Request/response models show detail structure

Red (new!) letter for indication each newly added api

This makes viewing and finding new api straightforward, esp. when there are often more than 40 api in such a long doc.

Figure 6. "New" indication

Related tickets will be added to where it's mentioned

I will specify all related tickets I found for this version, and add them to confluence on the specific part of doc. It will look like this. So the more specific your tickets are, the easier it will be for me to manually locate where these changes are actually referring to .

Figure 7. Specifying tickets for changes

Whereas in Jira, if I added that ticket (in this case its HWS-270) in a specific page of confluence. They will auto show the ref link (issue links--- the "also mentioned in" section) at the bottom of that ticket.

Figure 8. auto-link the Confluence pages for the tickets specified

So please let me know if there's anything you want to elaborate, or if my understanding on your changes and ticket referring is wrong.

We can hide something from public viewing, often unfinished part or changes prepared for the NEXT release, and that's why we need a quick review.

I still have questions for this wallet 1.2.8, but I can not find required info from jira . For example, there's no info about payout_bonus, unlock_bonus, cancel_bonus in the entire HWS (wallet) project

But these are new things in this version.

Figure 9. New implantation without discussion in Jira
 

I will ask developer K** and PM T*** about it before this Friday.

So book a time with me with your company Microsoft Teams , or I will book a google meet for you with my BnosK Google Meet account. (10 min is enough)

Anyone who is interested can also participate the review.

Please notice, the content reflected in attachment IS identical to the corresponding page in confluence at this moment.(Feb 9, 2022) But it may change without notice before its publication. We still need a review to slightly tweak for what should be shown to the public.


Best,

Howard Wu, as a member from {Your company} backend team, and as a Technical Writer from BnosK

 
 

留言

Translate