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

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

一,写博客的起源:

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

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

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

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

前年时我把一个编译安装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,
      而且文档也可以供给遇到同样问题的读者参考,

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

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

      那就很有意义了

      

原文地址:https://www.cnblogs.com/architectforest/p/14436436.html