TOTO.net

【Keywords: Technical Articles, article structures, paper, 技术文档，结构，如何写】

其实写技术文档是一个比较细致的活，看了很多的技术文档，转载来转载去，格式乱了不说，图片也没有了，看也看不清楚了。就算看到了一个国内作者原创的技术文档，总是感觉怪怪的。

我没有写过专业的论文，也没有研究过如何写专业的论文，技术文档也基本上看国外的，因为国外的组织的比较清晰，甚至有一些会提供PDF文档；而国内的技术文档很多的时候，都是一篇文章转载了n个站点，弄的你都不知道哪里是原创的地方，而且很多的时候（甚至可以说绝大部分是这样的），转载不注明来源，转载不注意图片以及文章格式等等。

让我尤其痛恨的是那些高校BBS论坛中的技术文档。我也是从BBS混过来的，?灌水?这样的名词相信大家都不会陌生。很多的BBS混子们为了那一点点的经验值，一点点的虚荣，拼命的灌水。基本上打开十七、八个IE窗口，打开一个到两个的终端，Ctril+C -> Alt+Tab -> Shift+Ins/Ctrl+w -> Enter….，一篇水文就出来了，很少很少有人会去注意内容是否需要重新排版一下，是否需要添加图片Link等等。我曾经有一个朋友能在4秒中内完成一次转贴（记得曾经BBS上对连续两个发贴是有时间间隔限制的，不是3秒就是4秒，反正那哥们已经接近极限了），一个晚上五，六百篇水文就这样炮制出来了（补充一句，那哥们写论文还是非常认真的，质量也非常的高）！

相对而言，国内的Web论坛基本上会好一些，但是也好不到哪里去。

最早的时候开始看国外的技术文档应该算是MSDN（更早的已经没有印象了，因为看到也不是特别的好看），当时就觉得MSDN太超值了，不仅版面漂亮整洁，字体漂亮得体，段落章节划分也非常的清晰，该有的Reference或者See Also 都组织的清清楚楚的（曾经看MSDN看的入迷了，See Also一个接一个的看下去，远远超过了当时需要查阅的内容范围）。后来接触了一些国外的其他站点，原创文章比较多，内容组织的都非常的精彩和漂亮，慢慢的也就对国内的技术文章失去了兴趣（在此，尤其要批评CSDN，里面的文章和人气是又多又旺，但是毕竟是网友编辑的，内容没有统一的风格不说，字体布局等等各方面都存在问题，以致于许多的大牛们在CSDN里面成名以后就离开了CSDN）。

Donald Knuth博士为了打印出来的论文好看一点，可以独力发明一套专业的排版系统Tex，而这套系统又是如此的完美，以至于科技论文方面，大家的标准就是用Tex（或者其衍生工具，LaTex,cTex之类的）来完成论文的排版。我没有用过，但是我知道，只要我想投稿一篇论文到国际专业期刊上，除了用Tex以外，我别无选择，MS Word虽然提供了可视化的公式编辑器，但是在专业人士眼中，毛病太多了，因为专业人士眼中，一篇好的论文不仅内容要好（当然，这是首要的），而且要让人容易看，容易懂。那么如此一来，必要的公式，必要的图表是少不了了，如此一来，必要的格式也是少不了的了（投过这样的专业期刊的人都会知道，如果你的格式不符合要求，人家的审稿人根本就不会给你审稿）。

MSR Asia的沈向阳博士曾经为了让各位本土的研究员能写出符合专业要求的论文，专门到USA去买了一套如何写英文论文的书。可见，一篇好的论文，格式与排版是何等的重要。

同样，写一篇技术文档，格式和排版也非常重要。这也是国内那些粗制滥造的技术文档，文档中心的通病。

我的个人站点，将在未来的时间中，陆续的推出一些技术文档，谈谈一些如何写技术文档的想法，不谈内容，只谈格式与排版，也算是对未来有一个规范。

首先，这些论文的载体。目前用的Blog系统是pLog，pLog作为一个Blog System，有其存在的好处和弱点。好处，当然是方便了写Blog，坏处就是不能生产出美观漂亮的文章（因为后台的编辑功能实在是太弱了）。这些技术文档不仅是作为对自己掌握技术的一个总结归纳，更是展示给别人看的。自己的文章只有通过了别人的认可，才算是有价值的，就象作家的存在价值和意义就在于有多少读者一样，所以这些技术文档的载体肯定是HTML，静态的HTML。因为我需要让这些技术文档不仅有一个明确的格式，而且有一定的风格，让你一看，就知道了，哦，这不是TOTO写的文档么？任何一个blog系统都无法满足我的要求，那我只有自己做。

定了载体以后，再继续讨论格式以及排版就有了基础。所以其次，关于格式。第一位的当然就是标题（可以有副标题，作者当然是我，就可以免了）；第二位的应该是KEYWORDS，这样就不会浪费观众的时间，也便于搜索引擎（例如Google，我喜欢Google）的检索归档；第三位应该是摘要，让人一看就明白这篇文章是否符合他正在寻找的内容要求；第四位不可或缺的就是一个目录，HTML如此方便的超链接岂能浪费？第五部分就是文章的正文，内容标题，内容一段一段的组织好，尤其注意是否有错别字（这一点着实比较难！）和语法错误（如果写英文的话）；第六部分，就是相关的引用资料，任何一篇技术文档都不可能是凭空造出来的，一定会有相关的引用，告诉大家，大家并不会因此离开我，相信反而会根据相关的内容来判断这篇文章的权威性和价值。

这样的一篇文章才能算是真正意义上的技术文档，当然这和论文有点类似，论文的格式比这个只会更加的严格，而我在上面提到了这些格式也只是根据我的经验和阅读习惯，认为在一篇技术文档中必须具备的要素。

谈完了格式，我们再继续谈谈排版。

排版涉及到了字体，字号，字体颜色，粗体，斜体，段落缩进，图片位置，图片精度，图片说明等等的情况。英文字体可以选择的比较多，但是作为一篇技术文档，并且在HTML上要供各种各样的Browser浏览，那可选择的就不多了。Windows平台上技术文档用的最多的字体是Verdana和Tohama，并且这两种字体在Linux平台和Unix平台上被支持的也非常好，看起来也不累，代码字体当然是用Courier New这样的等宽字体；中文字体也只有两种，宋体或者黑体；字号当然要突出标题，显著的表示出重点内容；字体的颜色如果没有区分那就是极大的浪费了HTML的本身功能，但是一篇文章中可以用到的颜色不可以超过3种；粗体和斜体在必要的场合会用到。段落格式自然按照中文或者英文本身的习惯；图片位置全部居中，带1px的边框，图片下面放置图片编号和说明。

另外还要特别注意的一点就是标点符号，标点符号分为英文半角和中文全角（当然只要是CJK和其他双字节的文字都会存在全角），一篇技术文档中使用的标点符号应该统一。

罗罗嗦嗦的写了一堆，其实只要能遵守一个基本的原则：?容易看，容易懂，不累?就可以了（当然，这是我的原则）。

希望能与看到了这篇文章，并且想写一些有价值的技术文档的朋友们共勉。