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


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

    一,写博客的起源:

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

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

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

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

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

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

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

          那就很有意义了

          

  • 相关阅读:
    敏捷手艺参考书籍
    算法一书配套网站
    一张图了解UML类图的所有关系
    如何团队合作--Team Geek
    正则--解析换行
    SourceTree基本使用
    springMVC--第一个demo
    Notepad++--去掉空格和换行
    ES 部分API
    spring--启动报错 Cause: org.xml.sax.SAXParseException; lineNumber: 1; columnNumber: 1; 前言中不允许有内容
  • 原文地址:https://www.cnblogs.com/architectforest/p/14436436.html
Copyright © 2020-2023  润新知