[TW. 2 ] thoughts from an advanced Technical writer

我稍微改了這篇的標題。因為我覺得這不是問答，而變成了體悟。

雖然如此，我認為還是很好的回答了一些很進階的疑問。這體悟不是空談玄學，而是真切的答案，必須不斷接受環境的挑戰精進後才能真實說出來。

"吾生也有涯，而知也無涯。以有涯隨無涯，殆已；已而為知者，殆而已矣"

"My life (career, capability) has a limit, but knowledge is boundless. It is futile to pursue infinity with limited life span and resource. Those who understand this but still strive to do so, will burn out themselves (with no reward)."  

This suggests that work smart is more important than work hard. For documentation or technical details or new skills, there will always be new tech replacing existing ones. But it will be futile if you just try all of them or recorded the endless low level changes (without the reasons behind choosing them). The key is to see the essence of business logic, and transform infinity into finite sets of components. So minimal effort can be made while gaining maximal reward --- without burning your team down.

庖丁解牛的故事內容和寓意比起強調精湛的技術更為重要。畢竟這是"養生主"的目的，也就是最精湛的技術其實是來自於對事物本質結構的見解。但中文圈以外，似乎只有故事被翻譯，其對於分群的變化見解卻沒有很好的被傳達。這是technical writing的另一個技術，把無限類別(open group) 化為有限 (closed group)，是在business logic上去描述程式部件的功能 (finite set) 而非不斷描述其新增或改動的細節 (endless detail)。

這是語言學的對於生字的分類方式，依照該特定語法功能做分群分類，如此便能囊括所有未來的新字。

 

Maximize the contribution of (new) technical writers

Bottom-up approach. Observe and follow rules. Before breaking the info silo
- Figuring out who is the target audience for the doc
- Prioritize info that is yet to be clarified for the stakeholders
- Write for features that are going to be available in next release

Top-down approach. Check where the largest chunk of info is, start breaking the silo by realigning  
- Let the other professionals work on their specialized fields
- Maintaining 'The single source of truth'
- Always let the others know what's on technical writers' hands now

Without async communication and autonomous mindset, remote work would be impossible for a growing company. Tasks would be siloed and unfulfilled.

I often have the feelings when I was working with a company with longer history. Certain core value must be withhold and emphasized all the time. Such an organization must have transformed numerous time but the core value is always well maintained.

Being the person in the middle needs to bring ''resilience'' to the organization. By resonating with the core value to reduce bureaucracy, it will level up entire system in a smooth manner. This is the metrics for a senior technical writer: identify contribution needed for an organization to it evolving with time.

What have you learned from your experience? Can you share with us?

"Reduce direct conflict". The technical writers are middlemen who served as a cushioned group, and become lubricant to other solid functional parts. Make async communication possible through good documentation,  and become supportive to the corporate goal.

Although confrontation is possible with the help of evidence-based writing or project management or version-control software (jira, github), direct confrontation does not help fostering a better team.
 

Human are inevitable to have weakness, so high value shall not be equivalent term to no error. Some people tend to do nothing to avoid mistakes. Instead of create value for a corporate, the lack of ownership spirit diminishes the corporate value. 'No error' does not mean high quality. We need acceptable error tolerance to find better solution. 

This is totally different from "forcing a way out" mentality. In my opinion, the approach is much feminine because the decision is made by careful consideration. Like a housewife who utilizes limited budget to get the best material for her family meal.

It's futile to maximize certain aspect of productivity

Technical writers are people who enjoys to "manifest the destiny". To align with higher social value or realization of  Tao (the way to ultimate harmony, or "michi" 道), they must use all the potential in them without burning themselves down.

There is always a gap between such a vision and reality, but technical writer are optimists who tend to believe the potential of kind people's relentless work. In my career, 80% of writing is descriptive based on existing programs and functionalities.

But there will always be new technical details or changes that coming out in the system, it would be futile to record the infinity.


The answer was told by an ancient Chinese cook. In the story "養生主: 庖丁解牛", a cook that masters the techniques of dismantling a bull, told the prince that at first all he could only see the whole body of the bull. After years of career he could cut through the joints in his mind right before his hands move, so minimal effort can be made.
 

"A regular cook worn out his kitchen knife within a month because he chopped. A good cook replace his knife annually. I had been using mine for 19 years yet it is still as sharp as the day it was made."

The transformation from brutal force to techniques, then to "the way". Infinite challenges can only be tackled by a true understanding of the limitation of one's finite resources, therefore one uses it with care.

Techniques is the knife, business logic is the joints. The core value is the way. An advanced technical writer follows the core value of the corporate and shape the documentation with it.

For certain functionalities that will be fulfilled and tested in next release, check if there's any changes in business logic. If not, it has lower priority for documentation.

Business logic is the realization of "the way" (by getting closer to the ideal design), so it always has highest priority for documentation. It could be an disaster if 1 is replaced with 0, like the Tokyo Stock Exchange incident in Oct 1, 2020. The change of business logic was not documented in user manual therefore the backup system didn't work as expected. This is the thing that must be reflected in documentation after the upgrade, but it was ignored.