如何寫出一篇高質量的技術解決方案文檔（一）

在幾年前，我在研究定位技術的時候，看過一篇帖子，裏面那篇文檔的描述性很是好，讓人思路清晰而且容易理解，給我留下了很深入的印象，因爲最近項目不是太急，閒來無事就想收集一些比較好的東西，忽然想起了這篇文章，可是因爲時間久遠，當時也沒有刻意記憶這篇文章的出處，也許今天它已經沉寂在網絡深海，但慶幸的是通過個人努力回憶，經過它在網絡中留下的蛛絲馬跡，終於找到了它。

在工做中發現了好的東西有時由於工做太忙，在看過了，用事後就忘記了，甚至是沒有時間去記錄和整理，很慶幸我有一個記憶力很強的大腦，或許由於當時，那些爲了找出解決方法的日日夜夜加深了個人記憶。

下面的內容，基本上是針對這篇對我印象深入的文章來展開討論的，我會把我比較欣賞的部分一點點的粘出。

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.

 

經過上面的翻譯和理解，這段文字先提出了一些假設性問題，而且對這些假設性問題提出了回答，而這些回答同時也是問題，而接下來這個文檔會對這些問題一一做答，當閱讀者看到這些問題時，就能夠判斷是否有和這篇文檔提出的問題有重合的問題，這決定了閱讀者是否繼續看下去的依據，若是沒有你想要的問題，即可以直接關閉以避免浪費時間，接下來這個文檔便進入到了最核心的部分，對問題的解決提供策略，因爲原文比較長，我就不對每個解決策略進行分析，基本上是一個套路的模式，我只挑出一個做爲講解，看看咱們能學到什麼。

接着往下看：