# 創建項目文檔 [TOC=2,3] 我們需要為我們的項目創建一個文檔，通常我們可以將核心代碼以外的東西都稱為文檔： 1. README 1. 文檔 1. 示例 1. 測試 通常這個會在項目的最上方會有一個項目的簡介，如下圖所示：  Github Project Introduction ### README README通常會顯示在Github項目的下面，如下圖所示：  Github README 通常一個好的README會讓你立馬對項目產生興趣。 如下面的內容是React項目的簡介：  React README 下面的內容寫清楚了他們的用途： - **Just the UI:** Lots of people use React as the V in MVC. Since React makes no assumptions about the rest of your technology stack, it’s easy to try it out on a small feature in an existing project. - **Virtual DOM:** React abstracts away the DOM from you, giving a simpler programming model and better performance. React can also render on the server using Node, and it can power native apps using [React Native](https://facebook.github.io/react-native/). - **Data flow:** React implements one-way reactive data flow which reduces boilerplate and is easier to reason about than traditional data binding. 通常在這個README里，還會有： - 針對人群 - 安裝指南 - 示例 - 運行的平臺 - 如何參與貢獻 - 協議 ### 在線文檔 很多開源項目都會有自己的網站，并在上面有一個文檔，而有的則會放在[https://readthedocs.org/](https://readthedocs.org/)。 > Read the Docs 托管文檔，讓文檔可以被全文搜索和更易查找。您可以導入您使用任何常用的版本控制系統管理的文檔，包括 Mercurial、Git、Subversion 和 Bazaar。 我們支持 webhooks，因此可以在您提交代碼時自動構建文檔。并且同樣也支持版本功能，因此您可以構建來自您代碼倉庫中某個標簽或分支的文檔。查看完整的功能列表 。 在一個開源項目中，良好和專業的文檔是相當重要的，有時他可能會比軟件還會重要。因為如果一個開源項目好用的話，多數人可能不會去查看軟件的代碼。這就意味著，多數時候他在和你的文檔打交道。文檔一般會有：API 文檔、 配置文檔、幫助文檔、用戶手冊、教程等等 寫文檔的軟件有很多，如Markdown、Doxygen、Docbook等等。 ### 可用示例 一個簡單上手的示例非常重要，特別是通常我們是在為著某個目的而去使用一個開源項目的是時候，我們希望能馬上使用到我們的項目中。 你希望看到的是，你打開瀏覽器，輸入下面的代碼，然后**It Works**: ~~~ var HelloMessage = React.createClass({ render: function() { return <div>Hello {this.props.name}</div>; } }); React.render( <HelloMessage name="John" />, document.getElementById('container') ); ~~~ 而不是需要繁瑣的步驟才能進行下一步。