zoukankan      html  css  js  c++  java
  • 如何写出一篇高质量的技术解决方案文档(一)

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

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

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

    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.

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

    接着往下看:

  • 相关阅读:
    vue父组件促发子组件中的方法
    油猴脚本:油猴脚本自动点击 | 自动检测元素并点击、休眠、顺序执行、单页面也适用
    油猴脚本:使用layer.js mobx lodash jquery
    vue项目统计src目录下代码行数
    常用mobx响应新值变化函数autorun和observe
    uni app使用mobx | uni app状态管理mobx
    File and Code Templates | webstorm代码文件模板 vue typescript
    javascript立即执行函数简单介绍
    VSCode 安装GitLens插件不生效问题
    常用的浅拷贝实现方法
  • 原文地址:https://www.cnblogs.com/rioder/p/4277663.html
Copyright © 2011-2022 走看看