如何写出一篇高质量的技术解决方案文档（一）

在几年前，我在研究定位技术的时候，看过一篇帖子，里面那篇文档的描述性很是好，让人思路清晰而且容易理解，给我留下了很深入的印象，因为最近项目不是太急，闲来无事就想收集一些比较好的东西，忽然想起了这篇文章，可是因为时间久远，当时也没有刻意记忆这篇文章的出处，也许今天它已经沉寂在网络深海，但庆幸的是通过个人努力回忆，经过它在网络中留下的蛛丝马迹，终于找到了它。

在工做中发现了好的东西有时由于工做太忙，在看过了，用事后就忘记了，甚至是没有时间去记录和整理，很庆幸我有一个记忆力很强的大脑，或许由于当时，那些为了找出解决方法的日日夜夜加深了个人记忆。

下面的内容，基本上是针对这篇对我印象深入的文章来展开讨论的，我会把我比较欣赏的部分一点点的粘出。

Flow for obtaining user location

Here's the typical flow of procedures for obtaining the user location:

1. Start application.
2. Sometime later, start listening for updates from desired location providers.
3. Maintain a "current best estimate" of location by filtering out new, but less accurate fixes.
4. Stop listening for location updates.
5. Take advantage of the last best location estimate.

Figure 1 demonstrates this model in a timeline that visualizes the period in which an application is listening for location updates and the events that occur during that time.

 

哇，忽然粘出这么多，非常压力吧！可是这应该是最细的颗粒了，你们能够先不看上面文章里具体的内容，由于可能文章内容不会在此次咱们的讨论之中，那咱们该讨论什么呢？在后面会详细阐述，follow me。

这篇文章是出自google的官方指导板块，目的是为了帮助开发者开发一个带有定位功能的App，感兴趣的能够查看原文http://developer.android.com/guide/topics/location/strategies.html。

Google团队考虑到，可能开发人员对让本身的App具备Location Services的功能这点来讲变得有点无从下手，对于解决方案的制定有些拿捏不得，甚至在深思熟虑后制定了错误的策略，为了减小上述的状况，而且提升开发人员开发的效率，帮助项目管理者制定更好的策略，因而这篇文章出现了。这篇文档文如其名，叫作——

Location Strategies

你能够把它翻译成定位策略或者定位机制，随你喜爱，它是一个复数形式，也就意味着，也许不是一条策略，这很是符合对现实项目中关于策略的定义，若是只有一条策略咱们还有什么好拿捏不得呢？

一篇好的文档标题必定是简洁明了，直达中心思想，在现实项目的运行过程当中咱们会看到各类形形色色的文档，有的时候，甚至大多数时候，文档的撰写者为了体现出文档的“专业性”，常常会出现冗长拗口的文档标题，这对于文档的阅读者形成了没必要要的引导，甚至是误导。

接着往下看：

Note: The strategies described in this guide apply to the platform location API in android.location. The Google Location Services API, part of Google Play Services, provides a more powerful, high-level framework that automatically handles location providers, user movement, and location accuracy. It also handles location update scheduling based on power consumption parameters you provide. In most cases, you'll get better battery performance, as well as more appropriate accuracy, by using the Location Services API.

To learn more about the Location Services API, see Google Location Services for Android.

note的出现，提示咱们这段文字你能够读一下，经过对这段文字的翻译，我发现它对本文档起到的实质性帮助并非很明显，有一点延伸阅读的意味，起初我觉得这种以Note开头的段落会有着更实质性的东西，这就有点像咱们项目开发详细设计文档中，有关于阅读面向对象描述与适用范围描述等性质的段落，它其中还包含了外部连接，很友好的提示阅读者若是对说起的部分感兴趣能够快速定位，而最后这一句 To learn more……更是将这篇文档所讨论的中心思想的出发点提示给了阅读者，这一切的源头即是 Google Location Services for Android。也许有人认为会稍显多余，读这篇文档的缘由就是在使用Google Location Services for Android时出现了疑问或者是问题。在一个严谨的文档中，我认为因果关系的描述必不可少，虽然咱们知道缘由是什么。固然，阅读者也能够选择不读，彻底不会影响对核心思想的理解。

接着往下看：

当……的时候

Knowing where the user is allows your application to be smarter and deliver better information to the user. When developing a location-aware application for Android, you can utilize GPS and Android's Network Location Provider to acquire the user location. Although GPS is most accurate, it only works outdoors, it quickly consumes battery power, and doesn't return the location as quickly as users want. Android's Network Location Provider determines user location using cell tower and Wi-Fi signals, providing location information in a way that works indoors and outdoors, responds faster, and uses less battery power. To obtain the user location in your application, you can use both GPS and the Network Location Provider, or just one.

经过对这段话的翻译理解，能够把这段所描述的内容定个性，那就是背景，或者环境，说是背景，你能够理解为某个事件的发生背景，好比某些历史事件在发生前的大环境，说是环境，你能够理解为在咱们开发过程当中为了让某个功能模块更针对性的工做，所配置的前提条件，更直白点说就是前提条件，不论是环境，背景，前提条件，都是为下面描述核心思想作铺垫的开胃菜，而这道开胃菜可不能随便乱点，必定要能约束核心思想的描述范围，也就是说，讨论内容只适用于当前问题。咱们看过不少技术解决方案，有不少一上来就是一个大标题，xx技术解决方案，紧接着 1,2,3……列出了技术解决的详细步骤，这是有很大的漏洞的，举例，若是在项目中对某一个功能的技术方案进行从新调整，首先应该了解旧方案的解决策略，由于讨论内容只适用于当前问题，若是没有对前提条件进行记录，在理解旧方案时就无据可查，形成调整的难度，若是当时实施旧方案的人员还在的话，他能够按照记忆力帮你回忆当时的背景，但谁说他就必定能记得住呢？

接着往下看：

Challenges in Determining User Location

咱们为何须要这份文档？由于…… 这是一个挑战！

当阅读者看到这样的信息时，心想也许我来对了地方，注意，我用的是也许，不是必定，和确定，由于阅读者尚未看到关于核心的内容，或者他看到这篇文档的途径是从别的外部连接引导过来的，好比一些搜索引擎的结果页，别人的日志博客里，并不清楚是不是本身想要的东西，也许这篇文档会帮助我解答个人疑惑，而这个标题的出现，则是告诉阅读者，你能够不看上面的全部，可是注意，接下来的内容你必定要看，由于，这将决定你是否继续阅读，或者干脆走人。

接着往下看：

 

Obtaining user location from a mobile device can be complicated. There are several reasons why a location reading (regardless of the source) can contain errors and be inaccurate. Some sources of error in the user location include:

• Multitude of location sources

  GPS, Cell-ID, and Wi-Fi can each provide a clue to users location. Determining which to use and trust is a matter of trade-offs in accuracy, speed, and battery-efficiency.

• User movement

  Because the user location changes, you must account for movement by re-estimating user location every so often.

• Varying accuracy

  Location estimates coming from each location source are not consistent in their accuracy. A location obtained 10 seconds ago from one source might be more accurate than the newest location from another or same source.

These problems can make it difficult to obtain a reliable user location reading. This document provides information to help you meet these challenges to obtain a reliable location reading. It also provides ideas that you can use in your application to provide the user with an accurate and responsive geo-location experience.

 

经过上面的翻译和理解，这段文字先提出了一些假设性问题，而且对这些假设性问题提出了回答，而这些回答同时也是问题，而接下来这个文档会对这些问题一一做答，当阅读者看到这些问题时，就能够判断是否有和这篇文档提出的问题有重合的问题，这决定了阅读者是否继续看下去的依据，若是没有你想要的问题，即可以直接关闭以避免浪费时间，接下来这个文档便进入到了最核心的部分，对问题的解决提供策略，因为原文比较长，我就不对每个解决策略进行分析，基本上是一个套路的模式，我只挑出一个做为讲解，看看咱们能学到什么。

接着往下看：