讓你的文檔從靜態展示到一鍵部署可操作驗證

作者：慕扉

用戶在根據文檔進行操作時，會出現根據文檔內容搭建環境困難、代碼調試失敗、功能無法使用的情況，主要是由於文檔中有年久失修、沒人維護、無法跑通的代碼，給用戶快速上手帶來很多的挑戰。

爲了解決文檔中的這些用戶體驗問題，通過函數計算的能力讓阿里雲的文檔從靜態展示升級爲動態可操作驗證，用戶在文檔中單擊一鍵部署可快速完成代碼的部署及測試。這一改變已在函數計算的活動沙龍中得到用戶的認可，你也快來體驗一下吧~~

用戶問題及痛點

阿里雲的產品作爲技術驅動型解決方案，用戶對文檔中提供的代碼示例有較高的依賴。通過分析，發現用戶在使用文檔時有以下問題。

文檔中提供的代碼錯誤，用戶無法直接使用

使用如下的代碼示例，在測試時一直報錯，導致用戶無法直接使用。 文檔中的代碼示例由於長時間未更新和缺乏維護，已經變得過時，這直接影響用戶使用文檔時的體驗。

代碼示例：	報錯信息：

文檔中只提供代碼片段，用戶調試門檻高

文檔中只提供代碼片段，缺乏完整的項目結構和環境配置指南，用戶需要自己搭建項目和設置運行環境， 才能使用文檔中介紹的功能，這無疑增加了用戶實際操作的難度，甚至會嚇退很多新手用戶。

文檔中沒有提供代碼，用戶無法參考文檔使用該功能

例如：函數計算的配置 OSS 文件系統文檔中，只提供給用戶如何配置 OSS 掛載，卻沒有提供如何訪問 OSS 掛載文件相應的代碼示例， 這直接導致用戶想使用該功能時參考該文檔無法獲取想要的信息。

原文檔內容：	用戶期待的文檔內容：

解決方案：提供動態可操作驗證的文檔

函數計算是一種 Serverless 架構模式，專注於事件驅動的函數編程，提供端到端的解決方案。用戶使用函數計算，不需要採購與管理服務器等基礎設施，只需編寫並上傳代碼或鏡像。同時函數計算支持多種編程語言，函數創建完成後可以快速調試驗證。

如果文檔中的代碼能夠部署在函數計算平臺，那麼用戶可以在文檔中直接操作驗證代碼提供的功能， 會直接提升用戶使用文檔代碼的體驗。

實現方案

整個解決方案的流程示意圖如下所示。

1. 通過 Serverless Devs 工具開發併發布完整代碼對應的應用模板。
2. 在文檔中配置一鍵部署，將代碼片段與應用模板關聯，併發布文檔。
3. 用戶在文檔中單擊一鍵部署後，根據應用名稱在函數計算部署應用，並可以直接測試代碼功能。

文檔效果

以使用函數計算部署通義千問大模型實現 AI 對話文檔爲例，介紹文檔動態可操作的效果。

用戶可以在文檔中使用一鍵部署的入口

1）文檔最上方

2）支持一鍵部署的代碼片段前面，重點提醒用戶可點擊。支持一鍵部署的代碼 codeblock 右上角

單擊一鍵部署後

單擊一鍵部署後，會根據配置的應用模板將代碼需要開通的服務、角色、配置的參數在面板中呈現，用戶需開通及配置。

部署並查看應用

1. 應用部署成功後，可以查看應用的基本情況。
2. 單擊操作列的測試，即可進入函數計算提供的測試頁面。
3. 在測試頁面，已默認將測試參數填入，單擊測試函數，即可根據參數進行函數調用。
4. 最終會返回函數調用返回結果。

用戶反饋

在 2023 年 12 月的函數計算活動沙龍中，有 70 多名用戶體驗了該文檔的一鍵部署能力。在 2024 年 1 月的活動沙龍中，有 2000 多名用戶參與任務的體驗，其中有 500 用戶完成。用戶反饋從文檔直接部署降低了體驗該功能的門檻。

總結

文檔中增加一鍵部署後有以下優勢：

1）用戶文檔使用體驗提升

原來用戶在文檔中看到的是文字說明及代碼片段，要自己搭建環境，構造完整的項目代碼使用該功能，耗時不僅長且容易出錯，對於新手用戶不友好。	現在用戶可以直接單擊一鍵部署即可以快速體驗該功能，不僅提高操作效率，還可以降低使用過程中的錯誤率。

2）快速驗證代碼的正確性

原來文檔中提供代碼，需要用戶單獨構建項目環境驗證保證代碼正確性，整體成本高。	現在文檔中的代碼已關聯完整的可運行代碼，可以快速部署驗證代碼正確性，降低代碼驗證的成本。

3）快速獲取完整代碼

原來文檔中的代碼大部分是研發提供的代碼片段，並未提供完整的代碼，導致代碼片段和可完整運行的代碼割裂，用戶無法快速從文檔獲取完整的代碼。	現在文檔中的代碼統一在 GitHub 倉庫維護，文檔中呈現代碼片段，每次變更可找到源碼修改，用戶可以通過文檔操作獲取到完整代碼。

最後

好的文檔應當超越文字的界限，成爲知識傳遞和技能培養的橋樑。阿里雲函數計算讓我們朝着這一目標邁出了重要一步。我們將文檔從傳統的靜態頁面升級爲一個動態的、互動性強的工具，用戶可以通過一鍵部署直接在函數計算平臺驗證文檔內容。這種轉變較大地提升了文檔的可操作性和實際應用價值，讓用戶不只是閱讀和理解概念，還能通過實際操作使用該能力。

我們誠邀所有用戶來體驗函數計算文檔從靜態到動態的轉變，希望通過你們的參與和反饋，不斷優化文檔，助力每位用戶在學習和使用文檔的過程中實現最大化的收益。

如果您希望體驗文檔的一鍵部署能力，可以訪問下面文檔鏈接。

• 使用函數計算部署通義千問大模型實現 AI 對話

  https://help.aliyun.com/document_detail/2623419.html

• 使用函數計算實現自動解壓上傳到 OSS 的 ZIP 文件

  https://help.aliyun.com/document_detail/2624066.html

• 請求處理程序（Handler）

  https://help.aliyun.com/document_detail/2512964.html

• 日誌

  https://help.aliyun.com/document_detail/2512968.html

• 錯誤處理

  https://help.aliyun.com/document_detail/2512969.html

• 快速創建函數

  https://help.aliyun.com/document_detail/2509023.html