开发markdown文档规范

随着项目越来越多,项目深度越强,对维护项目和持续开发带来了不少麻烦。先前的开发我们都没有对开发文档进行很好的整理与规范,如果一个功能扔出来,不解释半天另一个猴子也很难对接功能或者接手继续开发。

程序猴子间的交流并不够简明,将直接带来沟通成本的提高。其实最佳的猴子交流方式一般是,所谓的:
No BB , Just show me the code !

好记性确实不如烂笔头,不断的技术迭代与积累才是发展的基础。就是酱,所以每一个有追求的公司都应该为项目规范今后的文档撰写方式。

PROJECT的开发文档目录结构

每个项目下都需要有一个目录名叫

-- readme

readme目录下,要有个文件叫roadmap.md,这个文件记录的东西包括:

  • 功能节点的目标功能,以及负责人,完成时间等
  • 需要完善的细节
  • 一些特别重要的BUG
  • 下个版本需要迭代的功能和新增的功能
  • 一些重要的事件记录

readme文件目录下每一个开发猴子都需要以自己名字命名,如:

-- readme
  roadmap.md
  -- aaron
  -- shuaige
  -- dragon

每个猴子自己去管理自己的功能模块开发记录,根据自身习惯来记录,但无外乎记录的内容都要包含记录要点:

  • 每个功能的主要逻辑实现思路,重要代码注释
  • 功能实现的难点
  • 自己的排期规划
  • 自己认为需要迭代或重构的要点记录
  • todo
  • 需要给其他人对接的详细API接口
  • 认为未来需要交接给其他人的细节会被记录
  • 学习文档,未来可能会用到的代码记录

markdown语法参考

详细点的:
http://www.appinn.com/markdown/#hr
最简明的:
https://en.wikipedia.org/wiki/Markdown#Example
11种基本语法:
http://www.cnblogs.com/hnrainll/p/3514637.html

最后编辑于
©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 215,076评论 6 497
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 91,658评论 3 389
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 160,732评论 0 350
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 57,493评论 1 288
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 66,591评论 6 386
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 50,598评论 1 293
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 39,601评论 3 415
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 38,348评论 0 270
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 44,797评论 1 307
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 37,114评论 2 330
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 39,278评论 1 344
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 34,953评论 5 339
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 40,585评论 3 322
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 31,202评论 0 21
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 32,442评论 1 268
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 47,180评论 2 367
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 44,139评论 2 352

推荐阅读更多精彩内容

  • Android 自定义View的各种姿势1 Activity的显示之ViewRootImpl详解 Activity...
    passiontim阅读 172,012评论 25 707
  • 前端集成解决方案要求: 模块化开发。最好能像写nodejs一样写js,很舒服。css最好也能来个模块化管理! 性能...
    Www刘阅读 3,009评论 1 20
  • 先说项目开发过程中团队人员的分工协作。 一 人员安排 毕业至今的大部分项目都是独立完成,虽然也有和其他同事协作的时...
    SnowflakeCloud阅读 10,762评论 3 59
  • 从小,我就是一个不喜欢整理和打扫房间的“假”姑娘,别的小女孩房间都是整洁而干净,偏偏我的房间是一团糟,该放在书架上...
    俊哥不是哥阅读 292评论 0 1
  • 亲和我一起依窗来听雨关注我个人公众微信号326634322xiayufei 原创 文 夏瑜斐 爱我的人,我爱的人,...
    夏瑜斐的小木屋阅读 366评论 0 0