技术文档目录结构和写作规范

​

主旨

• 优雅简洁, 剔除糟粕和过时的内容, 突出实用和实践.

• 统一规范, 确保每一行代码都像是同一个人编写的.

  ​

• 国内第一个开源( 免费 )的Web前端完整课程体系.

• 名师团队协同撰写, 贡献最精华的干货.

  ​

• 方便查阅, 清晰的目录结构.

• 快速上手, 降低学习成本.

• 内容最新, 与最新技术保持同步.

• 内容权威, 案例有趣.

目录结构

A. 标准目录

本目录适用于编程语言 / 框架的语法和API的教程.

简介

• 版本(建议使用最新版本)
• 背景
• 基础

安装

• 安装方式
• 环境搭建

语法

• 定义
• 语法
• 基本用法(2)
• 应用场景(1)

进阶

• 部分源码实现原理( 可选 )

• 最佳实践( 面试题收集 )

• 相关资源推荐

• 学习路线图

B. 实战目录

本目录适用于综合技术的运用, 完整案例的具体开发流程, step by step. 不再赘述基础知识.

案例分析

• 需求分析
• 关键技术点

准备工作

• 项目目录结构

• 编程语言/框架/工具

• 服务器/数据库

开发流程

• 布局

• 实现功能

• 演示

案例总结

• 编程思想
• 常见错误
• 新技术
• 参考资料

通用规范

使用Markdown语法进行书写本文档, 方便规范格式和发布.

写作前, 请先学习Markdown基本语法.

1. 标题

Markdown语法为

#       一级标题
##      二级标题
###     三级标题
####    四级标题
#####   五级标题

标题可以分为五级, 请根据层级正确嵌套, 请勿一级标题嵌套三级标题.

一般内容写到三级标题, 案例要求细化到四级标题.

• 一级标题：教程名称

• 二级标题：每个章节的名称

• 三级标题：每个章节下的子标题, 如定义, 基本语法, 案例等

• 四级标题：子标题下的关键步骤( 按需求添加 )

• 五级标题: 每个步骤下的具体流程的节点( 按需求添加 )

2. 文本

• 代码

  Markdown语法为

  JavaScript
//这是代码块格式
let fun = function() {
console.log("hello, Markdown.")
}


  JavaScript 这是单行代码格式

• 使用情景

  • 基本语法

  • 基本用法

  • 关键代码段

  • 命令行

    $  git add hello.text    // 注意命令行开头要加 '$' 或者 '#' 

• 规范

  • 遵循代码书写规范, 参考前端代码规范.
  • 代码行数限制在 20 行内.
  • 关键步骤写明注释, 简洁明晰.

• 中文

  使用半角标点

  错误：ＪａｖａＳｒｉｃｐｔ （ ＪＳ ） 是一种“轻量级”解释型的程序设计语言。
  正确：JavaScript ( JS ) 是一种"轻量级"的解释型程序设计语言.

• 英文

  • 避免使用无意义的命名, 如var aaa111 = "sdgdsf"; function fff(){}.

  • 使用正确的英文拼写, 如iOS, JavaScript, jQuery, 而不是
IOS,javascript,jquery.

  ​

• 数字

  数字左右需要空格

  错误：2011年5月15日，我订购了5台笔记本电脑与10台平板电脑。

  正确：2011 年 5 月 15 日，我订购了 5 台笔记本电脑与 10 台平板电脑.

  ​

3. 列表

Markdown语法为

• 这是无序列表1

• 无序列表2

  1. 有序列表1
  2. 有序列表2

使用场景

• 无关联的同级的内容使用无序列表
• 连续的步骤使用有序列表

4. 句子

• 避免使用长句. 一个句子建议不超过 30 字或者正文的 1 行.
• 尽量使用简单句和并列句, 避免使用复合句.
• 避免使用形容词, 和代表个人主观的词汇.
• 避免使用网络用语.

5. 引用

这是引入的格式

使用场景

• 定义概念时, 可以引入官网的权威释义.
• 背景介绍
• 导语

6. 配图

不易理解的抽象的概念, 建议配图.

图片来源以官网为主, 请勿使用个人博客内的图片.

使用无水印图片或者使用软件绘制.

使用场景

• 头图

• HTTP网络传输

• 前后端数据交互, 如Ajax

• 设计模式, 如MVC

• 服务器 / 数据库相关内容

• DOM结构

  ​

7. 其他说明

• 分割线

每个章节完结后要有分割线.

第一章

第二章

​

• 强调

  例如: 使用Ajax进行前后端的数据交互

  ​

• 链接

  避免将网址直接复制在文章内, 应使用正确的链接格式.

​ 错误: 推荐阅读JavaScript语言精粹https://www.amazon.cn/JavaScript%BE%B7/dp/B0097CON2S

​ 正确: 推荐阅读JavaScript语言精粹

• 使用Tab缩进

正确使用缩进, 可以更好的体现出内容之间的层级关系.

这是外层内容,没有使用缩进
这是一个Tab缩进的内容
这是两个Tab缩进的内容

• 表格
  

  使用表格可以直观的展示比较的数据

Markdown资源

• Markdown编辑器(Web/客户端 Windows/Mac/Linux)
• GitBook
• Markdown Pad
• cmd-Markdown 作业部落
• Mou
• sublime

• Atom

  更多内容参考Markdown编辑器推荐