Bi-weekly report for api document

Hi Teams:

Spring is not far behind. Spring has arrived. Cherry blossoms (Feb) took over plum blossoms(Jan) in Northern areas, but they faded soon due to the warmth of cities. Do you know where you can still find beautiful cherry and plum blossoms in Taiwan?
You will have to go to mountain areas such as Wuling Farm, or Alishan (1000m and above). Those tourist spots are always as cold as winter even though it is located in central Taiwan. The cherry blossoms in Alishan can even last until April. So plan your time for the upcoming holidays. 

2016 April, the outskirt mountains in Southwest Taipei

Since the last down time(Feb 15, 2022) , we had the three services go live.

• Wallet 1.2.8 (RoC is high, since the available doc is made in Aug 2021)
• Member 2.1.13 (RoC = 0, only debug mode is disabled)
• Transmit 3.1.7 (RoC in Validation controller = 50%)

I already had these docs open to the public, but they are still under editing restrictions to only participants. If the service owner and PM didn’t respond after the stage, doc will be published. The average time slot between two downtimes is 2 weeks.

 
A full swagger porting to Confluence will take about 4 days, the time left for review will take about 2 days. The lifespan of a typical FP micro service is only 14 days long. Documentation would be helpful if a specific version of service is stable and can be selected as a LTS version for development in other departments. 

However, the doc shall not be a twist of reality. Your stakeholders often come to you and ask for frequent customization, or ask you to expose all your hidden api for more customization. This is when the red padlock in Confluence works —  keeping secrets only visible to our team members. 

Don’t make a good descriptive documentation become a prescriptive living nightmare for you. Use the red padlock, and tell me what you wish to hide from others during the doc review with me --- and your code reviewer (the Grand Master). Your doc is designed to save your lives, rather than destroying it. 

The doc will be published only after it passed the review, and it can be published on certain date you launch your service/products. 

Available Improvements

Expandable marco for all api request/response models will be available by default

The first available version of expandable macro is shown in member 2.1.13

This is useful especially you need to know the request/response structure and available options in detail.

Honorable mentions 

The pre-deployment note made by T*** is concise and accurate.

1. I recommend everyone to read it. Please keep up the good work, and share it with the team after S*****’s pre-deployment!
2. screenshot 
   
   
   
   

The change note made by G*** is concise and clear. But I would suggest everyone to directly update status in your project so changes can be specified on previous tickets.
 

It makes up for the missing gap in tickets. I recommend every developer to write a brief note in MD or office365, and save it as an attachment to the ticket. This is helpful since the tickets are not updated as frequently as it should be. 

Specify the availability of the service swagger you provide. Since service owners often change its content and version without prior notice, I will have trouble during the 4 days of porting to Confluence. For example, it was Transmit 3.1.6 when the swagger content was provided, but the version was upgraded to 3.1.7 silently. I can’t tell if there’s any content or format change.

Review content for your new version of microservice

 

The following methods are supported channels for reviewing your service documentation. This is the hybrid work style that BnosK was born for, and the the response to the booming documentation needs in East Asia and other parts of the world. All the customers can find their fit when choosing BnosK technical writing service.
 

On site support: Face to face 

I have always prepared two regular wireless mice connected to the same PC. Just book a time with me, and you will sit with me side by side, reviewing the api doc and I wrote beforehand. This is convenient and easy for clarification, I used to work with my former coworkers and employers in this way. It typically takes less than 10 min, and the content will be published right after our review — then you are all done. You will never need to reply to random messages from skype or get hassled by midnight phone calls after that. Just tell them “read the doc”.   

My day time workspace is near the 5F pantry. (內湖，竹城企業家大樓)
 

Online support: screen sharing 

Your content is always available for my online review if you are willing to book a time with me! Use your Company Microsoft teams, or I can book it with google meet from my side. Both methods will show a meeting link that is directly accessible to you, so all you need to do is book a time with me, I will clean up the rest of the fixes and writing tasks for you.

Microsoft Teams 

Without saying, the official IM for many companies. Booking is also snappy easy, go to your office 365 calendar,  pick your desired time slot, invite me and your PM for reviewing.

Google Meet

I will book a meeting for you by default after my part (Confluence porting) is done. Just notice that you should see a wave moving when you speak. You can test your microphone and see if you can hear the test music playing. In this mode, you don't need to install anything, your calendar will have a link for you to join that 10min review meeting.