Skip to content

Commit ab01cb5

Browse files
phodalphodal
committed
[marketing] add more docs
1 parent 96ffb5d commit ab01cb5

9 files changed

+186
-61
lines changed

‎chapters/05-tdd-with-autotest.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66

77
偶然间在开发一个物联网相关的开源项目——[Lan](https://github.com/phodal/lan)的时候，重拾了这个过程。不得不说提到的一点是，在我们的开发流程中**测试是由相关功能开发人员写的**，有时候测试是一种很具挑战性的工作。久而久之，为自己的开源项目写测试变成一种自然而然的事。有时没有测试，反而变得**没有安全感**。
88

9-
###一次测试驱动开发
9+
### 一次测试驱动开发
1010

1111
之前正在重写一个[物联网](http://www.phodal.com/iot)的服务端，主要便是结合CoAP、MQTT、HTTP等协议构成一个物联网的云服务。现在，主要的任务是集中于协议与授权。由于，不同协议间的授权是不一样的，最开始的时候我先写了一个http put授权的功能，而在起先的时候是如何测试的呢?
1212

‎chapters/07-github-marketing.md

Lines changed: 64 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ Vue 不是因为好用，而一下子火了。这一点我印象特别深，当
3333

3434
除此，还有一种可能是，你的 ID 不够 fancy，即你在社区的影响上比较少。此时，就需要**一点点慢慢积累人气**了。当你积累了一些人气，你就能和松本行弘一样，在创建 mRuby 的时候就有 1000+ 的 star。并且，在社区上还有一些相关的文章介绍，各个头条也由他的粉丝发了上去。如，一年多以前，我创建了 [mole](https://github.com/phodal/mole) 项目。
3535

36-
![Mole](mole.png)
36+
![Mole](./img/mole.png)
3737

3838
当时，是为了给自己做一个基于 GitHub 云笔记的工具，在完成度到一定程度的时候。我在我的微信公从号上发了相关的介绍，第二天就有 100+ 的 star 了，还接收至最一些鼓舞的话语。对应于国内则有：
3939

@@ -46,7 +46,7 @@ Vue 不是因为好用，而一下子火了。这一点我印象特别深，当
4646

4747
所以，你觉得呢？
4848

49-
编写 README
49+
编写一个好的 README
5050
---
5151

5252
在一个开源项目里，README 是最重要的内容。它快速地介绍了这个项目，并决定了它能不能吸引用户：
@@ -101,35 +101,80 @@ numbers, objects, strings, etc. Lodash’s modular methods are great for:
101101

102102
你会怎么写？
103103

104-
### hello, world 示例
104+
### 安装及hello, world 示例
105105

106-
在我们看完了上面的介绍之后，紧接着就是一个 hello, world 的示例。如 React 的示例：
106+
在我们看完了上面的介绍之后，紧接着接一个 hello, world 的示例。在运行 hello, world 之前，我们可能需要一些额外的安装工作，如：
107107

108108
```
109-
class HelloMessage extends React.Component {
110-
render() {
111-
return <div>Hello {this.props.name}</div>;
112-
}
113-
}
114-
115-
ReactDOM.render(
116-
<HelloMessage name="John" />,
117-
document.getElementById('container')
118-
);
109+
npm install koa
119110
```
120111

121-
这个
112+
如 Koa 的示例：
122113

123-
技术文档——手把手教会别人
124-
---
114+
```
115+
const Koa = require('koa');
116+
const app = new Koa();
117+
118+
// response
119+
app.use(ctx => {
120+
ctx.body = 'Hello Koa';
121+
});
122+
123+
app.listen(3000);
124+
```
125+
126+
作为一个程序员，你应该懂得它的重要性。
127+
128+
好在这里的安装工作只有两步，而不是：
125129

130+
![Lan 安装过程](./img/lan-example.png)
126131

127-
示例程序
132+
对于那些需要复杂的安装过程的软件，应该简化安装过程，如提供 Docker 镜像，或者直接提供一个可运行的 Demo 环境。以免用户在看完 README 之后，直接放弃了使用该库。
133+
134+
技术文档
128135
---
129136

137+
好了，依一个开发人员的角度，如果上面的步骤一切顺利的话，接下来，便是使用这个开源项目来完成我们的功能。这个时候，我们开始转移注意力到文档上了。
138+
139+
由于，之前在某一个项目，经历过一个第三方 API 文档的大坑——文档中只罗列了 API 的用法。如下 Intellij Idea 生成的结构图：
140+
141+
![API 示例](./img/api-examples.png)
142+
143+
文档中上，罗列了每个函数，以及每个函数需要的参数。我使用 Intellij Idea 直接反编译 jar 包，看到的信息都比文档多多了。文档上，没有任务示例，甚至连怎么初始化这个库的代码都没有。
144+
145+
WTF！
146+
147+
### 技术文档
148+
149+
对于一个复杂的开源项目来说，文档上要写明安装、编译、配置等等的过程。如下图所示：
150+
151+
![Python Social Auth 文档](./img/python-social-auth-example.png)
152+
153+
并且在我们发布包的时候，就要不断地去重复这个过程——如果你使用了自动化测试，那么这个过程便自动完成了。
154+
155+
如果我们的项目使用起来相当的简单，那么我们就可以只写一些示例代码即可。
156+
157+
并且，我们可以将文档直接入到代码里。它可以有效地减少文档不同步，带来的一些问题。
158+
159+
![Lodash 示例](./img/lodash-code-example.png)
160+
161+
上图是使用了 jsdoc 的 Lodash 示例。
162+
163+
### 更多的示例程序
164+
165+
示例代码本身也是文档的一部分，不要问我为什么~~。
166+
167+
反正，除了一个 hello, world，你还要有各种场景下的示例：
168+
169+
![Redux](./img/redux-examples.png)
170+
171+
没有这么多示例，敢说自己是好用的开源项目？
172+
173+
### 编写技术文章
174+
130175

131176

132-
吸引贡献者
177+
鼓励、吸引贡献者
133178
---
134179

135180

‎github-roam.md

Lines changed: 64 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -940,7 +940,7 @@ SQLiteHelper.prototype.getData = function (url, callback) {
940940
941941
偶然间在开发一个物联网相关的开源项目——[Lan](https://github.com/phodal/lan)的时候，重拾了这个过程。不得不说提到的一点是，在我们的开发流程中**测试是由相关功能开发人员写的**，有时候测试是一种很具挑战性的工作。久而久之，为自己的开源项目写测试变成一种自然而然的事。有时没有测试，反而变得**没有安全感**。
942942
943-
###一次测试驱动开发
943+
### 一次测试驱动开发
944944
945945
之前正在重写一个[物联网](http://www.phodal.com/iot)的服务端，主要便是结合CoAP、MQTT、HTTP等协议构成一个物联网的云服务。现在，主要的任务是集中于协议与授权。由于，不同协议间的授权是不一样的，最开始的时候我先写了一个http put授权的功能，而在起先的时候是如何测试的呢?
946946
@@ -1619,7 +1619,7 @@ Vue 不是因为好用，而一下子火了。这一点我印象特别深，当
16191619

16201620
除此，还有一种可能是，你的 ID 不够 fancy，即你在社区的影响上比较少。此时，就需要**一点点慢慢积累人气**了。当你积累了一些人气，你就能和松本行弘一样，在创建 mRuby 的时候就有 1000+ 的 star。并且，在社区上还有一些相关的文章介绍，各个头条也由他的粉丝发了上去。如，一年多以前，我创建了 [mole](https://github.com/phodal/mole) 项目。
16211621

1622-
![Mole](mole.png)
1622+
![Mole](./img/mole.png)
16231623

16241624
当时，是为了给自己做一个基于 GitHub 云笔记的工具，在完成度到一定程度的时候。我在我的微信公从号上发了相关的介绍，第二天就有 100+ 的 star 了，还接收至最一些鼓舞的话语。对应于国内则有：
16251625

@@ -1632,7 +1632,7 @@ Vue 不是因为好用，而一下子火了。这一点我印象特别深，当
16321632

16331633
所以，你觉得呢？
16341634

1635-
编写 README
1635+
编写一个好的 README
16361636
---
16371637

16381638
在一个开源项目里，README 是最重要的内容。它快速地介绍了这个项目，并决定了它能不能吸引用户：
@@ -1687,35 +1687,80 @@ numbers, objects, strings, etc. Lodash’s modular methods are great for:
16871687

16881688
你会怎么写？
16891689

1690-
### hello, world 示例
1690+
### 安装及hello, world 示例
16911691

1692-
在我们看完了上面的介绍之后，紧接着就是一个 hello, world 的示例。如 React 的示例：
1692+
在我们看完了上面的介绍之后，紧接着接一个 hello, world 的示例。在运行 hello, world 之前，我们可能需要一些额外的安装工作，如：
16931693

16941694
```
1695-
class HelloMessage extends React.Component {
1696-
render() {
1697-
return <div>Hello {this.props.name}</div>;
1698-
}
1699-
}
1695+
npm install koa
1696+
```
1697+
1698+
如 Koa 的示例：
17001699

1701-
ReactDOM.render(
1702-
<HelloMessage name="John" />,
1703-
document.getElementById('container')
1704-
);
17051700
```
1701+
const Koa = require('koa');
1702+
const app = new Koa();
17061703
1707-
这个
1704+
// response
1705+
app.use(ctx => {
1706+
ctx.body = 'Hello Koa';
1707+
});
17081708
1709-
技术文档——手把手教会别人
1710-
---
1709+
app.listen(3000);
1710+
```
1711+
1712+
作为一个程序员，你应该懂得它的重要性。
1713+
1714+
好在这里的安装工作只有两步，而不是：
17111715

1716+
![Lan 安装过程](./img/lan-example.png)
17121717

1713-
示例程序
1718+
对于那些需要复杂的安装过程的软件，应该简化安装过程，如提供 Docker 镜像，或者直接提供一个可运行的 Demo 环境。以免用户在看完 README 之后，直接放弃了使用该库。
1719+
1720+
技术文档
17141721
---
17151722

1723+
好了，依一个开发人员的角度，如果上面的步骤一切顺利的话，接下来，便是使用这个开源项目来完成我们的功能。这个时候，我们开始转移注意力到文档上了。
1724+
1725+
由于，之前在某一个项目，经历过一个第三方 API 文档的大坑——文档中只罗列了 API 的用法。如下 Intellij Idea 生成的结构图：
1726+
1727+
![API 示例](./img/api-examples.png)
1728+
1729+
文档中上，罗列了每个函数，以及每个函数需要的参数。我使用 Intellij Idea 直接反编译 jar 包，看到的信息都比文档多多了。文档上，没有任务示例，甚至连怎么初始化这个库的代码都没有。
1730+
1731+
WTF！
1732+
1733+
### 技术文档
1734+
1735+
对于一个复杂的开源项目来说，文档上要写明安装、编译、配置等等的过程。如下图所示：
1736+
1737+
![Python Social Auth 文档](./img/python-social-auth-example.png)
1738+
1739+
并且在我们发布包的时候，就要不断地去重复这个过程——如果你使用了自动化测试，那么这个过程便自动完成了。
1740+
1741+
如果我们的项目使用起来相当的简单，那么我们就可以只写一些示例代码即可。
1742+
1743+
并且，我们可以将文档直接入到代码里。它可以有效地减少文档不同步，带来的一些问题。
1744+
1745+
![Lodash 示例](./img/lodash-code-example.png)
1746+
1747+
上图是使用了 jsdoc 的 Lodash 示例。
1748+
1749+
### 更多的示例程序
1750+
1751+
示例代码本身也是文档的一部分，不要问我为什么~~。
1752+
1753+
反正，除了一个 hello, world，你还要有各种场景下的示例：
1754+
1755+
![Redux](./img/redux-examples.png)
1756+
1757+
没有这么多示例，敢说自己是好用的开源项目？
1758+
1759+
### 编写技术文章
1760+
17161761

17171762

1718-
吸引贡献者
1763+
鼓励、吸引贡献者
17191764
---
17201765

17211766

‎img/api-examples.png

134 KB
Loading

‎img/lan-example.png

153 KB
Loading

‎img/lodash-code-example.png

292 KB
Loading

‎img/python-social-auth-example.png

332 KB
Loading

‎img/redux-examples.png

317 KB
Loading

‎index.html

Lines changed: 57 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -148,15 +148,18 @@ <h1>GitHub 漫游指南</h1>
148148
</ul></li>
149149
<li><a href="#如何推广">如何推广</a><ul>
150150
<li><a href="#marketing-first">Marketing First</a></li>
151-
<li><a href="#编写-readme">编写 README</a><ul>
151+
<li><a href="#编写一个好的-readme">编写一个好的 README</a><ul>
152152
<li><a href="#这个项目做什么一句话文案">这个项目做什么——一句话文案</a></li>
153153
<li><a href="#它解决了什么问题">它解决了什么问题</a></li>
154154
<li><a href="#它有什么特性">它有什么特性</a></li>
155-
<li><a href="#hello-world-示例">hello, world 示例</a></li>
155+
<li><a href="#安装及hello-world-示例">安装及hello, world 示例</a></li>
156156
</ul></li>
157-
<li><a href="#技术文档手把手教会别人">技术文档——手把手教会别人</a></li>
158-
<li><a href="#示例程序">示例程序</a></li>
159-
<li><a href="#吸引贡献者">吸引贡献者</a></li>
157+
<li><a href="#技术文档">技术文档</a><ul>
158+
<li><a href="#技术文档-1">技术文档</a></li>
159+
<li><a href="#更多的示例程序">更多的示例程序</a></li>
160+
<li><a href="#编写技术文章">编写技术文章</a></li>
161+
</ul></li>
162+
<li><a href="#鼓励吸引贡献者">鼓励、吸引贡献者</a></li>
160163
</ul></li>
161164
<li><a href="#开源项目维护">开源项目维护</a></li>
162165
<li><a href="#如何以正确的姿势阅读开源软件代码">如何以“正确的姿势”阅读开源软件代码</a><ul>
@@ -1601,7 +1604,7 @@ <h2 id="marketing-first">Marketing First</h2>
16011604
<p>这一点相当的有意思，如果你的想法好的话，那么大家都会肯定，点下链接，为你来个 star。那么，你就获得更好的动力去做这件事。项目也在开头的时候，获得了相当多的关注。而如果大家觉得你的项目没有新意的话，那么你懂的~。</p>
16021605
<p>除此，还有一种可能是，你的 ID 不够 fancy，即你在社区的影响上比较少。此时，就需要<strong>一点点慢慢积累人气</strong>了。当你积累了一些人气，你就能和松本行弘一样，在创建 mRuby 的时候就有 1000+ 的 star。并且，在社区上还有一些相关的文章介绍，各个头条也由他的粉丝发了上去。如，一年多以前，我创建了 <a href="https://github.com/phodal/mole">mole</a> 项目。</p>
16031606
<figure>
1604-
<img src="mole.png" alt="Mole" /><figcaption>Mole</figcaption>
1607+
<img src="./img/mole.png" alt="Mole" /><figcaption>Mole</figcaption>
16051608
</figure>
16061609
<p>当时，是为了给自己做一个基于 GitHub 云笔记的工具，在完成度到一定程度的时候。我在我的微信公从号上发了相关的介绍，第二天就有 100+ 的 star 了，还接收至最一些鼓舞的话语。对应于国内则有：</p>
16071610
<ul>
@@ -1613,7 +1616,7 @@ <h2 id="marketing-first">Marketing First</h2>
16131616
<li>不成器的微博</li>
16141617
</ul>
16151618
<p>所以，你觉得呢？</p>
1616-
<h2 id="编写-readme">编写 README</h2>
1619+
<h2 id="编写一个好的-readme">编写一个好的 README</h2>
16171620
<p>在一个开源项目里，README 是最重要的内容。它快速地介绍了这个项目，并决定了它能不能吸引用户：</p>
16181621
<ul>
16191622
<li><strong>这个项目做什么？</strong></li>
@@ -1655,22 +1658,54 @@ <h3 id="它有什么特性">它有什么特性</h3>
16551658
<li>Creating composite functions</li>
16561659
</ul>
16571660
<p>你会怎么写？</p>
1658-
<h3 id="hello-world-示例">hello, world 示例</h3>
1659-
<p>在我们看完了上面的介绍之后，紧接着就是一个 hello, world 的示例。如 React 的示例：</p>
1660-
<pre><code>class HelloMessage extends React.Component {
1661-
render() {
1662-
return &lt;div&gt;Hello {this.props.name}&lt;/div&gt;;
1663-
}
1664-
}
1661+
<h3 id="安装及hello-world-示例">安装及hello, world 示例</h3>
1662+
<p>在我们看完了上面的介绍之后，紧接着接一个 hello, world 的示例。在运行 hello, world 之前，我们可能需要一些额外的安装工作，如：</p>
1663+
<pre><code>npm install koa</code></pre>
1664+
<p>如 Koa 的示例：</p>
1665+
<pre><code>const Koa = require(&#39;koa&#39;);
1666+
const app = new Koa();
1667+
1668+
// response
1669+
app.use(ctx =&gt; {
1670+
ctx.body = &#39;Hello Koa&#39;;
1671+
});
16651672

1666-
ReactDOM.render(
1667-
&lt;HelloMessage name=&quot;John&quot; /&gt;,
1668-
document.getElementById(&#39;container&#39;)
1669-
);</code></pre>
1670-
<p>这个</p>
1671-
<h2 id="技术文档手把手教会别人">技术文档——手把手教会别人</h2>
1672-
<h2 id="示例程序">示例程序</h2>
1673-
<h2 id="吸引贡献者">吸引贡献者</h2>
1673+
app.listen(3000);</code></pre>
1674+
<p>作为一个程序员，你应该懂得它的重要性。</p>
1675+
<p>好在这里的安装工作只有两步，而不是：</p>
1676+
<figure>
1677+
<img src="./img/lan-example.png" alt="Lan 安装过程" /><figcaption>Lan 安装过程</figcaption>
1678+
</figure>
1679+
<p>对于那些需要复杂的安装过程的软件，应该简化安装过程，如提供 Docker 镜像，或者直接提供一个可运行的 Demo 环境。以免用户在看完 README 之后，直接放弃了使用该库。</p>
1680+
<h2 id="技术文档">技术文档</h2>
1681+
<p>好了，依一个开发人员的角度，如果上面的步骤一切顺利的话，接下来，便是使用这个开源项目来完成我们的功能。这个时候，我们开始转移注意力到文档上了。</p>
1682+
<p>由于，之前在某一个项目，经历过一个第三方 API 文档的大坑——文档中只罗列了 API 的用法。如下 Intellij Idea 生成的结构图：</p>
1683+
<figure>
1684+
<img src="./img/api-examples.png" alt="API 示例" /><figcaption>API 示例</figcaption>
1685+
</figure>
1686+
<p>文档中上，罗列了每个函数，以及每个函数需要的参数。我使用 Intellij Idea 直接反编译 jar 包，看到的信息都比文档多多了。文档上，没有任务示例，甚至连怎么初始化这个库的代码都没有。</p>
1687+
<p>WTF！</p>
1688+
<h3 id="技术文档-1">技术文档</h3>
1689+
<p>对于一个复杂的开源项目来说，文档上要写明安装、编译、配置等等的过程。如下图所示：</p>
1690+
<figure>
1691+
<img src="./img/python-social-auth-example.png" alt="Python Social Auth 文档" /><figcaption>Python Social Auth 文档</figcaption>
1692+
</figure>
1693+
<p>并且在我们发布包的时候，就要不断地去重复这个过程——如果你使用了自动化测试，那么这个过程便自动完成了。</p>
1694+
<p>如果我们的项目使用起来相当的简单，那么我们就可以只写一些示例代码即可。</p>
1695+
<p>并且，我们可以将文档直接入到代码里。它可以有效地减少文档不同步，带来的一些问题。</p>
1696+
<figure>
1697+
<img src="./img/lodash-code-example.png" alt="Lodash 示例" /><figcaption>Lodash 示例</figcaption>
1698+
</figure>
1699+
<p>上图是使用了 jsdoc 的 Lodash 示例。</p>
1700+
<h3 id="更多的示例程序">更多的示例程序</h3>
1701+
<p>示例代码本身也是文档的一部分，不要问我为什么~~。</p>
1702+
<p>反正，除了一个 hello, world，你还要有各种场景下的示例：</p>
1703+
<figure>
1704+
<img src="./img/redux-examples.png" alt="Redux" /><figcaption>Redux</figcaption>
1705+
</figure>
1706+
<p>没有这么多示例，敢说自己是好用的开源项目？</p>
1707+
<h3 id="编写技术文章">编写技术文章</h3>
1708+
<h2 id="鼓励吸引贡献者">鼓励、吸引贡献者</h2>
16741709
<h1 id="开源项目维护">开源项目维护</h1>
16751710
<h1 id="如何以正确的姿势阅读开源软件代码">如何以“正确的姿势”阅读开源软件代码</h1>
16761711
<blockquote>

0 commit comments

Comments
 (0)