恭喜你，你是 有能力的独立开发者. 从你卑微的出身, 也许是做测试员, 你已经晋升为团队开发人员, 然后是高级开发人员, 现在你又迈出了一步, 它们中最大的, 直接与客户打交道.

但是其他的转换都是线性的，最后一个是指数的. 而在过去，你从与客户打交道或本身从事软件业务的雇主那里获得工作命令, 现在所有这些责任都被分配给了专家测试, 项目管理, 等.，都是你的。. 和 now you’re working with clients who are not in the software business; they’re in another business that needs a piece of software, 他们也不清楚自己想从你身上得到什么. 这是一个比表面看起来更大的挑战.

注:这里我描述的是那些希望自己的开发者拥有一个人的团队的小型客户. 这并不是自由职业者唯一的选择, 而这并不是我们在Toptal的唯一客户, 但这是我最喜欢的路线. 当然，如果你在团队中工作，而不是 独自一人，下面的一些将不适用. 例如，如果你在使用 敏捷方法 or Scrum，你可能会希望你的里程碑结构略有不同.

你们都听说过沟通的至高无上的重要性. 你不能通过Skype得到几句简短的描述，然后说 “三个月后我干完活了再见。.” 你必须与你的客户保持沟通，在你工作的每个阶段都要确保你对目标有一致的想法, 因为很少有客户会给你发送线框图和详细的功能规格说明. 您将对软件应该做什么、看起来像什么以及流程有一个大致的了解. 如果您基于通常开始时的粗略描述编写应用程序, 你的客户几乎不可能对结果感到满意. 在每个阶段，你都必须不断迭代以接近协议.

我在自己从事软件业务的公司工作了多年, 团队中的每个人都来自相同的文化, 说同样的母语, 在同一个走廊工作, 每天见面, 等.，值得注意的是，该公司 仍然 一半的时间都得不到它想要的. 毫无疑问，这里的挑战是巨大的.

为什么软件设计文档很重要

所以，当你接手一个新项目时， 在你打开Xcode或Visual Studio之前，你需要有明确和一致的设计目标. 这些目标应该在规范文档中建立. 如果客户没有写的话, 你应该写下来, 并在您打开IDE之前提交给他们进行审查. 和 如果你遇到一个客户说, “我们没有时间写设计文件”, 坦率地, 你应该放弃这个项目 因为前方有麻烦. The specification need not be particularly lengthy; it can be just a few pages, 但至少它应该布局用户界面, 包括线框(如果有UI组件), 设定完成的里程碑.

没有 这个文档, 你最终会陷入一个尖刻的模棱两可的循环, 客户对他们告诉你的和你告诉他们的有争议, 愤怒地发送以前通信的剪切和粘贴, 解释和争论，直到客户要求您进行更改以使应用程序符合“他们实际要求”的时候,并希望你无偿地做出这些改变.

与 这 软件设计 文档, 当出现分歧时，你会有一个答案, 您可以参考客户同意并签字的规范, 指出你已经完全履行了承诺. 你要对文件进行修改和澄清，而不是愤怒地争论. 如果有的话，客户会为一开始让不精确的信息泄露而道歉.

我们都希望客户满意. 我们都希望建立友好的工作关系. 我们都想要出色完成工作带来的骄傲. 但如果对工作内容有任何模糊，这些目标就无法实现 is. 如果你的客户说设计文件是太多额外的工作, 你的工作就是向他们解释 真正的 当由于某种误解而需要进行修改时，就会出现额外的工作. 如果客户 仍然 坚持要你在没有文件的情况下前进, 你应该接受这样一个事实:你们的关系不可行，然后离开.

软件设计规范应该具体说明什么?

至少, 它应该是对所需应用程序的描述, 完成标准, 和里程碑. 还记得, 您正在共享的内容最好被描述为需求和功能文档, 不是实现规范. 除非特定的实现是明确的客户目标，否则如何使其工作取决于您.

用户界面

大多数项目都是应用程序，而不是库或框架. 但是，如果你碰巧有一个这样的交付，算你幸运，因为 用户界面无疑是设计文档模板中最有问题的组件，而且几乎总是导致误解. 许多客户会给你发送完美的插图在图形编辑器创建的图形设计师谁不是一个程序员. 但问题是:这些插图并没有说明动画，控制状态(游戏邦注:如游戏).g.这个按钮被禁用了吗? 当它无法使用时是否会消失?)，甚至当按钮被按下时要执行什么动作.

在开始编写这些插图背后的代码之前, 你应该能回答所有这些问题. 具体来说，你应该知道:

1. 控件是否总是可见和/或启用? 它们的状态在什么条件下改变?
2. 看起来像位图，是按钮吗?
3. 这些状态和视图之间发生了什么转换? 以及它们应该如何被激活?

如果由您来为客户机的并发生成UI, 反过来做同样的事情:使用线框工具并创建一套完整的屏幕布局, 包括视图在不同应用程序状态下显示的任何变体. 这可能是一项详尽而乏味的工作, 但是您不会后悔的——它可以使您避免由于一个带有重大含义的小误解而重新编写大量代码和重新创建接口. 如果您正在创建一个双重应用程序(例如.g.，两者都适用 iPhone 和iPad)，为两者创建单独的线框.

屏幕尺寸也很重要. iPhone的屏幕有三种尺寸(截至撰写本文时). 单独的线框图为3.5英寸和4英寸的屏幕可能过多了, but you may have to make them; in most cases, 你可以简单地改变比例.

如果您的客户为您提供图形, make sure that they are correctly sized with the proper aspect ratios; morphing any bitmap that has text or objects (like circles) will introduce distortions. 如果它们不匹配，告诉客户用匹配的尺寸重新创建它们. 不要想当然地认为你可以拉长一个3.把5英寸的画面变成4英寸的画面，然后跟着滚动.

功能

在应用程序设计文档中要问的关键问题:

• 应用程序做什么，它做得有多快?
• 什么是可能的故障条件?它们是如何处理的?
• 哪些一次性操作是在第一次执行时完成的.e.，安装后)?
• 如果用户创建了任何类型的条目(例如.g.(书签)，限制是什么?

概括这些想法, 尽可能详细和彻底，因为这里的错误或误解将意味着重写代码.

里程碑

您的规格模板应该布局清晰的里程碑. 如果你的客户编写功能和用户界面设计, 随后，你们应该就一系列里程碑达成一致. 有时这些也是计费阈值, 但至少它们提供了一个明确的完成指标. 里程碑 may be in terms of functionality and/or components; they may even be separate applications if the gig involves a suite of deliverables. 如果可能的话，里程碑的持续时间应该大致相等.

软件设计规范示例

在这里，我将布局一个适当的设计文档的示例结构. 当然，这个模板应该根据需要进行调整. 另一个例子，参见 Joel Spolsky的样本规格，基于… 这帐面价值. 他对这份文件的看法略有不同，但有着相似的观点.

目标说明

包括一个简短的段落来描述这个项目和它的目标受众.

功能描述

应用程序是什么? do? 用户将遇到什么样的应用程序状态(核心用户场景的高级描述)?

例如，你的功能描述可能是这样的:

• 第一次运行
• 创建一个新的_____(游戏，搜索等).)
• 操作
• 背景和前景行为

用户界面

包括每一页的线框图，详细描述:

• 每个控件，包括状态(启用/禁用/高亮显示)和操作.
• 支持的方向和它们之间的转换.
• 功能代表.
• 错误处理.
• 尺寸和约束.

以下是我最新的iOS应用程序NotifEye的线框图:

如果你感兴趣的话，我用 Balsamiq的线框图工具.

例如，你的 用户界面描述 可能看起来像:

• 导航栏
  • 左导航控件:返回首页
  • 标题栏:当前屏幕或操作名称
  • 新建按钮:创建一个新事物
• 表视图
  • 章节0:章节标题
  • 第0节行:
    • 行控件0 (e).g.、图片)
    • 文本行0
    • 文本行2

里程碑

如上所述，完成的最后期限和预期的可交付成果.

例如，设计文档模板中的里程碑部分可能是这样的:

1. 外观应用程序显示屏幕和临时过渡和示例图像/文本
2. 通信协议:应用程序连接到网络/服务器
3. 功能里程碑1:…
4. Alpha应用程序(功能齐全)
5. 稳定
6. 释放

确保软件文档保持相关性

我并不是说一旦你和你的客户在规格文件上达成一致，设计阶段就结束了. 总会有一些你们都没有考虑到的细节, 你和你的客户都会知道, 在看中间结果时, 遇到新想法, 设计更改, 意想不到的设计缺陷, 不可行的建议.

设计将不断发展，并且应该在您的文档中捕获更改. 在我25年的工作经验中, 我从来没有做过这样的项目——包括我自己的应用程序(I.e.在那里，我是我自己的客户). 即便如此，我还是创建了包含详细规格的设计文件，并根据需要进行调整.

最重要的是，保持联系. 一周至少几次, 联系你的客户, 汇报你的进展, 要求澄清, 确保你们有相同的愿景. 作为你沟通的试金石，试着确保你和你的客户给予 相同 以下三个问题的答案:

1. 开发者刚刚在做什么?
2. 开发者目前在做什么?
3. 开发者接下来要做什么?