为什么这么多企业文档如此糟糕?

我花了很大一部分专业工作时间阅读技术文档。 也许“通读”并不是描述它的正确方法。 在这一点上,它更像是快速扫描菜单,常见问题解答和段落标题,以获取在哪里可以找到所需确切信息的线索。 除了某些例外情况,无论是我只是想快速确认正确的命令行语法,还是想让自己了解一种全新技术,这种情况都很常见。 基于Web的技术文档:性能不佳的艺术 现在,我对那些提供详细语法指南和手册页的人没有任何抱怨-他们为什么要重新格式化整个文档以突出一些我可能有一天会去寻找的晦涩细节? 但是,当我试图向自己介绍一个复杂的软件包时-要弄清其目的和主要用例-那么我有理由期望有一个相对可预测且舒适的实现目标的途径。 取而代之的是,我经常遇到一个项目主页,其中包含指向多个目标的链接,这些目标的名称为“入门”,“如何使用…?”,“文档”,并深深地埋在几个菜单层的“快速入门指南”下。 通常,我发送到的页面不完整,显然是改变主意和预算超支的受害者。 其他将涵盖该软件的过时版本,这些过时版本可能具有与最新版本明显不同的功能集。 更糟糕的是:这些功能实际上可能仍然存在,但是从那时到现在,它们已经更改了名称甚至图标。 即使我们忽略了写作的质量(控制起来可能非常困难且成本高昂)和单个文档的可理解性,似乎经常还会出现重大的版本控制和项目管理问题。 我通常可以猜测发生了什么:一些客户抱怨说他们无法弄清楚如何使用该软件,因此管理层(无法自行正确评估文档的当前状态)命令从头开始创建一套完整的新软件。 。 该项目开始了,但是大约一半的时间里,主要贡献者要么离开了公司,要么因其他截止日期和需求而分心。 直到有更多的客户抱怨他们也无法弄清楚如何使用该软件,才坐下来。 冲洗。 重复。…

IT项目中的黑洞猜想:破碎的Windows理论

在IT行业工作了多年之后,我观察到一种经常发生的现象,这种现象非常可怕,但同时又使我好奇地研究该主题。 很多时候,软件项目就变成了“黑洞”,在这里,怪异而神秘的力量开始吸引人们,金钱,幸福或周围的任何美德,最终它们变成了一个平行的世界,里面的人并没有真正知道问题的深刻和复杂性。 这些黑洞周围的文化经常很糟糕,无序是规则,缺乏社区意识和沟通才是王道。 我的意图是通过表达我多年来面对并与这些黑洞作斗争的观点,假设和经验来推测这一主题,并在一系列文章中进行探讨。 破碎的Windows理论 在一个比喻中,如果您的项目曾经是一颗璀璨的星辰,但最终开始在各地使用毒品,开始每周两次获取快餐,没有人能够立即阻止这些不良行为,那么成为黑洞的过程将会越来越多更强,症状将越来越明显。 这是我这些年来观察到的最大症状之一,可以借鉴社会科学家James Q. Wilson和George L. Kelling的理论来解释,他们在报告中指出犯罪,反社会行为和内乱的明显迹象营造一种城市环境,鼓励进一步犯罪和动乱,包括严重犯罪。 这组作者建议,针对故意破坏,破坏公共场所饮酒和逃票等轻微犯罪的治安方法有助于营造秩序和合法氛围,从而防止发生更严重的犯罪。 经常停止关注次要细节的软件项目后来常常成为破碎Windows的受害者。 例如,如果您的团队曾经开发过单元测试,但是突然有一个团队成员停止这样做,那么如果社区协调您的团队允许这种行为,那么整个团队可能也会停止这样做。 在解决这些小问题之前,社区中散布的主人翁意识和责任感起着重要作用。 反社会行为是黑洞中经常出现的另一种症状,其特征是长期无视或侵犯了社区其他成员的权利。 他们可能会表现出傲慢自大,对别人卑鄙和消极的态度,对自己的有害行为表示re悔。 我无需提及,这种环境不会带来任何好处,如果没有任何治安方法来阻止它,那么黑洞将统治并吸收所有这些。…

为什么每个软件开发人员都需要博客

博客是您可以用来作为软件开发人员推销自己的最佳媒介之一。 我坚信,每个关心自己职业的软件开发人员都应该投资创建博客。 为什么博客如此重要? 从简历和简短的面试中评估软件开发人员的技能通常很困难,因此许多雇主很难确定某人是否适合工作。 但是,想象一下,如果软件开发人员拥有最新的博客会发生什么。 该博客可能包含有关该开发人员的重要信息,包括代码示例以及对软件开发各个方面的深入技术分析。 通过阅读他或她的博客,我可以了解有关软件开发人员的更多信息。 拥有博客不仅可以帮助您找到更好的工作,还可以帮助您成为更好的软件开发人员并提高沟通技巧,并且可以带来您可能从未想到的各种机会。 如果您是自由职业者,或者对自由职业感兴趣,那么您会发现,成功的博客可以为您带来许多客户,而无需您出去寻找他们。 直接来找您的客户会更愿意支付更高的价格,而说服您雇用您的工作就会少得多。 如果您的博客访问者源源不断,则可以围绕他们的兴趣构建产品,并将其流量直接转化为客户。 开博客的另一个好处是可以提高您的沟通技巧。 组织您的想法并将其付诸实践是一项困难但有价值的技能。 定期写作可以帮助您提高技能。 当您定期发布博客时,您还将不断刷新自己的技能,并保持专业领域的最新信息。 您是否确定需要博客? 好。 然后你的下一个问题…