建立适用于中国的文档标准

net_robber

原帖由 jeffwang8001 于 2006-8-30 13:08 发表
正如楼主所说，有的文档大而全，让人看起来摸不着头脑，根本找不到主要的内容。

我感觉，是阅读者的水平不适合文档的水平

有些东西适合初学者，有些东西比较适合技术大拿之间交流

文档前面最好能够标出文档的主要阅读对象

就像孩子们刚刚学英语，你给他看牛津，难了。你给那些英语老教授看牛津，简单了。但是你给我看牛津，我觉得正合适


或者康熙词典，这里又有几人能看懂？？？

james.liu

cu是否可以考虑将帖子做成问题，答案方式。

然后设定一些关键词，，这样找起来很方便。

flyee_cn

这方面偶有些心得，做着应该还成。

我家老婆最美丽

有人提就有人做。

建议分类建立文档，比如针对应用软件系统可以分成技术特性，应用范围，选择方法，实施案例。这样会比较系统，而且避免集中在一个文档中让人觉得太大。新手看起来也清楚，不至于知其然不知其所以然。

开个头试试？

fluke888

原帖由 net_robber 于 2006-8-30 16:16 发表

我感觉，是阅读者的水平不适合文档的水平

文档前面最好能够标出文档的主要阅读对象

非常赞同您的观点！！个人认为这个提议很有价值。

科学球

其实我最近正在写文档，主要原因是我公司有几个同事是新入行。要慢慢给他们讲，真的要花好多时间。而如果他们不会，我面临的就是累死了局。

而我好多用户其实是不看文档的。他们习惯于出了问题就给我写mail或者打电话。作为他们的支持者，我经常问各种用户他们希望看到什么。

总结下来一共4点。

1。一本字典。这个字典包含了这个项目中所有的问题。在这个字典里，他们总是能找到答案或对应的方法。
2。一篇不要很长的文档，这个文档要告诉他们日常该如何做，遇到问题该如何做？怎样收集我说的那些信息。这类文档通常都是一些表格，或者命令，或者一些shell的脚本。
3。每个问题的说明。这个要更加简短。因为这个给用户老板看的，因此不能太深奥，也不能太不着边际。通常这种文档都要帮助用户工程师把他们的责任推干净，而我们的产品，发生这类问题也仅仅是偶尔的。
4。原文手册。我只有一个用户喜欢这类文档。他看文档象看小说一样津津有味。而这个用户也是我遇到最可怕的用户。因为我学艺不精，面对他胡说八道就是找死。不胡说八道又圆不起来。

而给工程师看的则是两篇

一篇是一个现场的帮助。这个文档绝对不要求长，3，4页即可。做到即使这个工程师事前没有看过，到用户现场现看，也来得及实施，或者也有的做，以等待援军的到来。

另一篇则是原厂文档的完美补充。设计所有小知识，小技巧，经验杂谈，忠告，警告甚至与之相关的周边知识。做到让阅读的工程师能够不去网上瞎找好多天，就能对这个产品有既宽广，又深入的了解。


这样看，其实这些文档是可以放在一篇里的。而形成一篇之后，我们就会得到该产品的一个真正适用于现场工程师的文档。有很多厂商其实已经这么做了，比如SUN的EIS等等。但是，EIS依然是美国人写的。说实话，我能看懂，而且也能很快的看懂，但总是缺少一些东西，直到做过很久，回头再看时，才发现，啊，这里其实我做的有疏漏，那里其实是有风险的。

我提出制作这样的文档，就是为了帮助所有现场工程师，让他们在文档的帮助下，既快，又完善的完成一次实施。同时，这还可以充实CU文档库。

我这个想法越来越完美吧。。。。哈哈哈哈哈哈

hellhell

我说一下我以前的公司的关于文档方面的东西吧，软件公司，可能偏重于软件工程方面：
1，文档是流程的产品，一个流程走到一个的程度，就要出相应的文档，文档是和代码一样重要的东西，过milestone都要一起交付的，公司经常有一个现象，到了快milestone赶工加班，不是写代码，而是写文档。
2，文档是标准化的，必须要有模板，我们公司的文档模块放在clearcase的服务器上。每份文档都有一份相应的文档说明，对文档模块的内容逐项解释。
3，有专人或专门的team进行流程和文档的改进工作，一个QA team的工作的一项就是升级文档模板，使之更好的符合流程。

纳兰婷

支持下下~~

山中无老虎

如果大家都有这个想法，建议大家把自己的行业写一下（比如系统集成、存储、软件等），然后根据情况建立一个组织机构，再根据不同的行业分成小组，大家定期交流。如果象现在这样，是不会干成。我想大家都知道象牙塔的故事吧。

aixy

个人认为，文档这东西，关键在于简洁明了、主题明确，格式并不是很重要，非要强调格式的话，往往会导致文档冗长、空洞，控制不好或者文档书写者对文档格式理解不好的话，就有可能会出现为了文档文档的情况，即为了填满文档格式要求的某些部分，加进一些无关紧要的东西，让阅读者费尽心思才能找到真正需要的东西。