文档：用博客做技术文档的总结

今天对自己的博客做一点总结：

一，写博客的起源:

最早的时候我的技术文档是保存在几个笔记软件中，

印象笔记，讯飞笔记，有道云笔记，

这几个软件我都充了会员，

有需要时从笔记软件中查找即可，

前年时我把一个编译安装php7.1的文档发给了一个同事，

他告诉我说文档在php7.4上不能用，

确实有编译参数在新版本的源码上不支持，

于是我考虑原有的把文档保存在笔记中的方式可能不够好，

文档在软件版本迭代后需要更新自己也不知道，

所以在博客园开设了这个博客

 

说明：刘宏缔的架构森林是一个专注架构的博客，地址：https://www.cnblogs.com/architectforest

         对应的源码可以访问这里获取： https://github.com/liuhongdi/

说明：作者:刘宏缔 邮箱: 371125307@qq.com

二，用博客的形式记录文档，怎样才能比较规范有实用价值?

1,尽量写实际操作的步骤，而不是copy官方文档

      如果说到全面，我们自己记录的文档肯定不如官方的文档全面，

      但不建议直接复制官方文档到自己的博客中，

      我的做法是如果有官方文档的地址，则把地址写到博客中供读者参考，

      博客内容更注重实际操作的内容：

      如何调用一个java的第三方库？如何安装并操作一个linux命令?

      这个对于我们更实用.

 

2,文档要实用，注明相关软件的版本号，参考之下可以实际操作成功

      互联网上的文章非常多，百度一下出来一大把，

      但很多文章没有说明当时操作的软件或库的版本，

      如果照着操作，就会发现api已经废弃或者命令的参数已经不可用，

     所以需要把版本号注明：

     linux命令的版本号，

     安装的jdk/php/mysql的版本号

     java的第三方库的版本号等，

     最起码在文章中所标明的版本下可以复现所描述的功能

 

3, 效果要能够测试

     写了很多代码，一执行报错了，

     写了很多命令参数，一执行失败了，

     所以博客中写到的内容要经得起实践检验，

     代码如何执行，如何测试，

     返回的结果是什么？是否达到我们的目标

     这一部分也要写在文章中，

      供读者参考，

      也更让人更容易理解文章所描述的功能 

 

4, 技术版本不要太旧，已淘汰的技术没必要再总结:

       it技术一直在快速发展，新技术不断涌现，

       旧技术一直在淘汰，

       如果旧的技术已经失去官方支持，

       则失去了我们对其进行总结的必要，

       例如：

       linux的ReseirFS,

       adobe的flash,

       borland的delphi

       mysql的myisam

       这些技术如果再总结以后使用到的概率极小，

       虽然觉得自己的知识库中的内容被淘汰很可惜，

       但不值得再在上面花费太多的时间和精力

 

三，写博客的意义何在？

      一个人的记忆力再强也不可能用过的技术全部都能牢牢记住，

      如果遇到问题而且这个问题曾经解决过，

      则找到当时的文档就OK,
      而且文档也可以供给遇到同样问题的读者参考，

      目前所总结的技术内容只是使用过的很小的一部分，

      计划每当有时间时就总结一些，对自己对读者都有一点点帮助，

      那就很有意义了