docsify 不一样的文档工具

俗话说"无规矩不成方圆"，但是我要说无规范不和谐，你可能觉得言重了「言重个毛」，下面就简单的说一下吧

来一个场景对话吧，以开发一个 APP 为例子来说明「纯属虚构，如有雷同那真是中奖了」，小明「开发 client」，小张「开发 server」

如此类似的事情的在需求、产品、销售、运营等等各个地方都会出现，何也--没有规范，最后导致权责不明，各干各的，反工是家常便饭，更甚者会干起架来 ...

无规范不和谐，花很小的代价获取更多大价值有时就体现在规范当中，规范最好以书面的形式「别拿嘴说，谁也不会记的」，规范的编写有多种形式，今天我们就来看看其中一个 docsify「文档网站生成工具」

规范基本上都以文档的形式出现的，写文档我们可以使用的工具实在太多了，小到记事本，大到一个综合软件太多太多了，先说一下笔者主要使用的文档编写工具，分为两个阶段「未了解 markdown 之前和之后」

现在我大部分使用 gitbook 来记笔记和写文档，只要把 markdown 语法熟悉了玩起这些来都是小菜，、csdn、掘金等自媒体平台都支持 markdown 了，markdown 一定要掌握「现在还不懂 markdown 那就太 low 了」，简单的说一下 gitbook 的流程

gitbook 有多种玩法，有兴趣的可以看看这部分内容

用官方的话来说 docsify 一个神奇的文档网站生成工具，如果看过 vue 的官方文档界面那就相当于看到了 docsify 生成的界面了「很清爽有么有」

docsify 不同于 githbook 和 hexo 它不会生成将 .md 文件化成 .html 文件，这些转化工作都是在运行时进行的

比如阿里 weex ui 的开发文档

这里就不一一列举了，可以查看 https://github.com/docsifyjs/awesome-docsify/blob/master/README.md 的 showcase 部分

这样就安装完了 docsify 命令行工具「前提要安装 node」，安装完以后我们就可以使用 docsify init ./docs 初始化项目了，然后运行 docsify serve docs 就可以在本地跑一个 server 来看到对应生成的网站了

我们就来一个 API 接口文档吧，大概完成以后这样的

还做一个国际化「只做了英文版的--装个 B 」,直接点击上面导航的 EN 来 Look 一下

怎么样够 B 格吧 ,服务端把这个文档给出一扔，还管个毛毛呢，直接并行开发吧「还 qq 对接？，还拿嘴对接？」

由于 docsify 的文档非常的详细，我们照着一点点的配置和编写半个小时就能入门，这里我们就把以上完成的 API 文档目录解析一下

主页 index.html

侧边栏 _sidebar.md

侧边栏对应的网页左边的导航页

_coverpage.md 封面

user/READMD.md

user/README.md 对应的就是 user 的主页，在这个例子中我们在此中写登录接口

对应的就是我们在上图中看到登录接口「我们再来看一下，如下图」

其它的 .md

其它的 getuserlist.md/getuserifno.md 都是侧边栏对应的接口界面，这里就不一一说了，和登录界面是一样的「不细说了，文档介绍的非常详细」

我们大概介绍完了所制作的文档，这里起一个抛砖引玉的作用，完了可以看 Demo 的源码「上传到 github 上，后面放出地址」

可以定制主题、还有一插件列表「搜索、统计、在 github 编辑等等插件」，也可以自己开发插件等「非常丰富，我们可以看官网查看」

我们写的文档可以部署在 GitHub Pages 上，也可以部署在所有的静态文件服务器上等

这节我们简单介绍了一下 docsify 文档编写工具，只是起了一个抛砖引玉的作用，具体的好多玩法大家可以自行去探所，当然拿 docsify 来写笔记是非常不错的「笔者一直使用 gitbook 来写笔记」，还可以用它来写个博客啥的都是不错的

如果还不熟悉 markdown 语法的，建议现在就看一定要把它掌握了「简单又牛 B ，写个模版什么的使用 markdown 再适合不过了」

案例地址： https://github.com/tigerchain/docsifydemo

作者: TigerChain 订阅查看更多内容。

本文出自 TigerChain侃大山

公号: TigerChain

对于刚开始进入IT的新人来说，“必备技能”往往意味着一个长长的、标有重要度的学习列表，但是过长的列表通常会导致新人不知如何开始学习，压力倍增。本文尝试列举出最重要的几个技能，也期望通过此列表能给新人一个比较明确的学习重点和路径。

深入学习一门编程语言

没有掌握任何一门编程语言，就不可能成为一名编程人员。

许多程序员试图在学习之初一次学习几种编程语言，以便应对他们第一份软件开发工作的需要。虽然我认为开发人员最终会学习多种编程语言， 但建议不要在开始时这样做。

因为同时学习多种语言只会导致混乱，也会分散学习其它技能的精力。相反，我建议深入的学习一种编程语言，这样也会对使用这种语言编写代码感到非常有自信。

如何组织代码

新手程序员在完成编程语言的学习之后，或者最好在学习编程语言的同时，需要掌握的是如何正确的组织代码。

通过Steven McConnell所著的《Code Complete》，可以帮助学习这个宝贵的技能。

组织代码意味着编写良好的、清晰可理解的、不需要大量注释的代码，因为代码本身是可自注释的。许多软件开发人员究其整个职业生涯都不曾具备这样的技巧，但是这个技能却是判断一个软件开发人员的技术和能力的首要标准。良好的代码结构代表的不仅仅是完成了编码工作，而是对编码事业的热衷奉献。

对于新手程序员来说，简洁清晰且含义明确的代码，能让你轻松地通过面试。

提升代码结构已经成为了软件开发的重要部分，但是提升的过程却是十分严格的。在这个过程中，虽然不需要编写新的代码，但是却需要和团队成员一起花费大量时间来维护现有的代码。

测试

现在，很多的软件项目都采用了所谓的敏捷流程，软件开发人员和测试人员合作的更加密切。代码质量成为了整个开发团队的责任，所以开发人员也需要对测试知识有一定了解。

对于开发人员来说，至少应该熟悉以下的基本术语：

- 白盒测试

- 黑盒测试

- 单元测试

- 边界条件

- 测试自动化

- 验收测试

面向对象设计

为了应对软件开发中的面向对象设计思想，开发人员也需要学习一种面向对象的语言。

面向对象设计是一种设计复杂程序的方法，它将代码分成了单独的类和对象（类的实例），这些类和对象封装了一些特定的功能。

我们一直试图在软件开发中管理复杂性，用对象的方式思考就能帮助我们做到这点。面向对象允许我们跳出一堆关系繁杂的组件，来清晰的定义和设计一个复杂的系统。

现在已经有大量的功能性编程语言，但是在软件开发过程中，你会发现那些最受欢迎的语言和模型都深受面向对象设计的影响。所以就需要深入的理解类、继承以及如何使用，还有多态和封装。

数据结构和算法

软件开发人员应该熟悉以下的数据结构：

- 数组或向量

- 链表

- 堆栈

- 队列

- 树结构

- 哈希

- 集合

掌握并熟练运用以上的数据结构，能帮助开发人员清晰的定义、存取、管理数据。通过合理的数据结构和算法，许多困难的编程问题就能迎刃而解。

常见的算法有以下几种：

- 排序算法

- 查找算法

- 图搜索算法

- 动态规划算法

- 模式匹配算法

善于利用好的算法，能起到事半功倍的效果。如果你对算法不够熟悉的话，就很难提出一个好的解决方案，这也就是需要我们掌握算法的原因。

事实上， 数据结构和算法也是软件开发中最有趣的领域之一。利用数据结构和算法来开发一个干净、简洁的解决方案，效果会非常好。

Gayle Laakmann McDowell的“Cracking the Coding Interview”书中介绍了有关算法和数据结构的所有知识。

学习这些知识是一个挑战，但却是非常值得的。掌握其中的任何一个技能，都能让你远远超过其他人。这些知识也正是其它软件开发人员所不具备的。

开发平台与相关技术

应该至少对一个开发平台以及与之相关的技术或框架有一定的经验。

平台通常意味着操作系统（OS），但它也适用于与操作系统类似的其他抽象系统。例如，你可能是专注于Mac或Windows操作系统的Mac开发人员或Windows开发人员，同时你也可以是专注于特定Web平台的Web开发人员。

具备某个特定平台的专业知识，不仅仅意味着需要熟悉平台本身，还需要掌握开发平台常用的开发工具、模式和通用框架。

框架与技术栈

除了学习特定的编程语言和平台外，学习并掌握一个框架和技术栈也是非常重要的。

框架是一组用于在特定平台或多个平台上开发代码的库，它通常会使该平台上的常见编程任务更加容易。例如，大多数C＃开发人员使用.NET Framework编写C＃应用程序。.NET Framework由许多库和类组成，允许C＃开发人员在更高层次的抽象中工作。

技术栈则与框架有点不同，技术栈是一组通常包括框架的技术，通常一起用于创建完整的应用程序。技术栈使得创建应用程序变得更加容易， 因为它们提供了许多开发人员用于开发应用程序的常见范例，因此可以轻松共享知识。

学习技术栈是非常有价值的，因为这意味着你拥有开发完整应用程序所需的所有技能。许多使用特定技术栈开发应用程序的公司，也在寻找熟悉该技术栈的软件开发人员。

数据库基础知识

目前， 主要有两种数据库技术：关系数据库和文档数据库。

现在的开发人员应该很熟悉关系数据库，但同时也应该对文档数据库有所了解。

在软件开发中，数据库通常用于存储应用程序的数据。

对于数据库，开发人员至少应该了解以下方面：

- 数据库的工作原理

- 如何执行基本查询来获取数据

- 如何插入、更新和删除数据

- 如何添加数据集

源代码管理

管理源代码是任何软件开发项目不可或缺的组成部分。在使用源代码之前，应该有一个网络来共享项目的所有文件。

源代码管理工具最基本的功能，是保留软件项目中对文件所做更改的历史记录。它还允许多个开发人员同时处理相同的代码， 并将这些处理代码融合在一起。

所有的开发人员都应该知道如何使用源代码管理工具，以便能够检查代码并从多个来源融合代码。

构建和部署

目前，大多数软件开发项目都有一些自动化的构建和部署系统。同时也有许多不同的软件应用程序，来帮助团队自动化构建和部署任务。

构建

当你编写代码并将其合入到源代码管理系统中后，你想通过一些方法了解你合入的代码是否运行的很好，这就需要进行构建。构建会编译系统中的所有代码，并确保没有编译错误。一个复杂的构建系统还可以运行单元测试和用户测试，或者代码质量检查，并提供一些有关代码库当前状态的报告。

部署

部署系统负责将代码部署到产品机器上，或者将其部署到某种测试环境中。

虽然开发人员不一定要成为部署方面的专家，但是了解系统的基础知识以及构建和部署代码的过程也是非常的重要。

调试

对于软件开发人员来说，经常会花费90％左右的时间，来弄清楚自己的代码为什么不起作用了。不论你从事任何语言的代码开发，代码调试都是开发过程中不可缺少的一部分。

所以开发人员应该下定决心，认真的学习如何做到高效的调试代码。

方法论

一些软件开发团队在编写代码并完成他们的项目时，都遵循着一些方法论。所以开发人员至少应该熟悉诸多最常见的软件开发方法论中的基本几种，这里要说的就是瀑布开发和敏捷开发。

总结

尽管本文中列举的软件开发人员应该了解的知识很多，其中很多知识也许正是你所不了解，但是请不要沮丧。我们要做的就是认真的补充这些知识，不断的提高自己。

---