> 原文出處：http://www.infoq.com/cn/news/2015/09/readme-io 那些包含著相對較新工具的文檔，比如@Asciidoctor和Cyrille Martraire的領域驅動設計啟示書《動態文檔》，是軟件開發過程中被忽略的最大領域之一，如今終于得到了大家的些許關注。對于一個API文檔來說，其被認為是至關重要的。Gregory Koberger正在開發一套系統，可以讓開發者文檔與API和API儀表盤更直接地對接。 最近InfoQ采訪了[Readme.io](https://readme.io/)的首席執行官Gregory，為了實現他對于API文檔的愿景，其創建了這家公司。 **InfoQ****：您能描述一下創建****Readme.io****背后的故事嗎，以及它是如何演化的？** > **Gregory Koberger****：**當然可以，首先我是一名程序員及設計師，并且對開發工具感興趣，因為在那片領域有著一套獨特的設計挑戰魅力。 > > 我曾經花費了大量的時間用來寫作和閱讀文檔，但是我認為應該有更好的方式實現它。大約五年前，我下定決心我要潛心專研這片領域，但是剛開始的時候我度過了一段艱難的時期。謝天謝地的是，像Stripe和Twilio這樣的公司已經向人們展示了文檔的重要性。大約一年前，我們成立了這家公司。 > > 公司運行的非常好。我們也確實發現，一份更優秀的文檔能夠在某些產品和問題上發揮好的作用。我們正走向希望人們開始改變對文檔的原有看法這一步。它不應該是一成不變的。它應該隨著閱讀它的群體和閱讀群體的知識量而改變。 **InfoQ****：您對****Readme.io****的愿景是什么？** > **GK****：**API由三部分組成：文檔、儀表板（用來生成開發者密匙等）和API本身。 > > 我想著手把它們整合到一起。API了解代碼和數據。儀表板了解用戶。文檔習慣上仍是一成不變，對它們一無所知。 > > 比如，想象一下，如果文檔知道用戶語言，并且可以直接顯示代碼片段，或者想象如果文檔知道用戶犯了某個具體的錯誤，并能夠幫他解決這個錯誤。 **InfoQ****：當需要記錄****API****時，您的****API****團隊主要面臨的挑戰是什么？** > **GK****：**一個大問題是,記錄API文檔不是一個優先事項。人們包括我自己都非常不善于記錄某個API。很難回到從前，猜測新人在使用你的API時需要了解哪些東西。并且很難永遠保持文檔是最新可用的。 **InfoQ****：****Readme.io****是如何幫助人們的？它的主要特點有哪些？** > **GK****：**目前，我們主要專注于文檔。就像WordPress專注于代碼和API一樣。我們讓您在為客戶提供開發體驗時變得更加容易。 > > Readme已經能夠支持表單、登錄頁面、教程等等。我們讓人們在在網頁上正確地使用API，進行變更，允許他們看看會發生什么。我們同樣能夠從GitHub上自動同步API文檔并友好的展示出來。 **InfoQ****：****Readme.io****與其它開源替代方案相比如何，比如****Swagger UI****或****Slate****？** > **GK****：**Readme.io有一個優勢是公司的所有人都可以參與其中，不僅僅是開發者。很快我們將支持Swagger，這樣我們就可以替換Swagger UI。同樣我們認為，社區也應該參與到文檔的記錄過程中。因此，我們有一些建議性的編輯器：公司內部或者外部人員可以通過一個友好的拖放編輯器提交更改意見。 **InfoQ****：****Readme.io****創建的文檔可以部署到某個現有的開發者門戶網站嗎？** > **GK****：**我們的目標是成為一個開發者中心。目前，你可以在一個現有的中心使用它。在未來，我們希望將文檔，儀表板和支持整合到一塊。當它們都在同一個地方時，它們真的會一起運行的很好。 **InfoQ****：你們支持****API****定義語言嗎？比如****Swagger****，****RAML****和****API Blueprint****。** > **GK****：**是的。目前我們用一種叫做[APIdoc](https://readme.io/)的東西。不久我們將會發布對[Swagger](http://swagger.io/)，[RAML](http://raml.org/)和[API Blueprint](https://apiblueprint.org/)的支持。 > > 與編寫段落文本相比，通過語義上記錄你的API，你可以創造更多的價值。因為你可以著手給用戶定制生成SDKs或者代碼示例。 > > 現在，我們僅限于導入這些語言，但是，我們認為讓人們導出語言同樣的重要。Readme.io很幸運能夠站在開發體驗中心的舞臺上，我們真的想利用這次機會成為不同API公司的交流中心。 **InfoQ****：你們是如何支持各種****API****開發工作流的，是代碼優先還是****API****優先？** > **GK****：**通常，API僅僅是以復制主網站構建的方式編寫。那是一個很糟糕的事情，因為很多時候，你用API做一些網站不能做的事情。 > > 所以，我認為將API看做網站的一個獨立的實體是很重要的，因為你希望它足夠的靈活，能夠做一些網站不能做的事情。 **InfoQ****：您認為哪種方式能最好的描述****API****，并且能夠與其實現的演化相同步？** > **GK****：**現在有很多種方法可以描述API，比如Swagger，RAML和API Blueprint。我們選擇APIdoc，是因為這種文檔非常接近代碼本身。它類似于Javadoc，這種文檔是對代碼的一種注釋，而不是一個單獨的文件。我們可以從GitHub上自動同步。 **InfoQ****：在一個典型的****API****團隊中，誰應該負責記錄****API****？** > **GK****：**每一個人都應該。習慣上來講，只有開發者做記錄。但是，API對業務、市場營銷和產品管理團隊同樣非常重要。我們希望實現每個人從開發者到CEO都能夠更新與他們相關聯的文檔。 > > 我們認為社區對記錄文檔擁有難以置信的重要意義，因為他們有其他人所沒有的疑問和用例。 **InfoQ****：從您的觀點來看，****API****文檔和操作的****API****管理是否應該分開處理？** > **GK****：**我真的很喜歡這個API的生態系統。現在有很多公司在做具體事情，并且做的很好。而對于較大的API管理公司，什么事都想自己做 但大部分做的很差。 > > 我認為API管理和文檔應該分開，但是，它們應該被更緊密的集成起來。 **InfoQ****：請問****Readme.io****下一版本的推出時間和新功能有哪些？** > **GK****：**我們正在做一個重大的重新設計工作，大約需要一個月左右的時間。除了看上去更加美觀，我們將為參考指南和示例設置單獨的版塊。 > > 對于文檔編寫人員，事情的發展和文檔中應該包含哪些內容變的更加明顯。對于終端用戶，將會更容易知道從哪里獲取他們想要的信息。 > > 因為我們想著手自動化記錄您API更多的過程，所以像Swagger導入之類的事變的非常重要。 > > 大部分開發人員都要花費時間閱讀或者編寫文檔。它是我們與代碼庫或API進行交互的界面，而且我真的很高興Readme正變的有能力改變人們以往的方式。 你可以嘗試免費版的[Readme.io](http://readme.io/)，并且它保留了免費的開源項目。對于專屬軟件，企業在Readme.io子領域提供了一個基本包，包括3個文檔版本和一個管理員用戶，花費$14/月。開發者中心版本允許您使用自己的域名，并且支持10個管理員用戶，花費$59 /月。 **查看英文原文：**[Interview with Readme.io Founder on the Future of API Documentation](http://www.infoq.com/news/2015/08/readme-io)