zoukankan      html  css  js  c++  java
  • 文档:用博客做技术文档的总结

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

    一,写博客的起源:

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

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

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

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

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

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

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

          那就很有意义了

          

  • 相关阅读:
    Struts2+Spring3+Mybatis3开发环境搭建
    spring+struts2+mybatis
    【LeetCode】Populating Next Right Pointers in Each Node
    【LeetCode】Remove Duplicates from Sorted Array
    【LeetCode】Remove Duplicates from Sorted Array II
    【LeetCode】Binary Tree Inorder Traversal
    【LeetCode】Merge Two Sorted Lists
    【LeetCode】Reverse Integer
    【LeetCode】Same Tree
    【LeetCode】Maximum Depth of Binary Tree
  • 原文地址:https://www.cnblogs.com/architectforest/p/14436436.html
Copyright © 2011-2022 走看看