API文档的最佳做法

API现在是其游戏中的佼佼者。 市场在增长,产品正在开发和改进。 这意味着API文档也将成为未来几年的关注焦点。 由于该领域的特殊性,API文档是非常独特的产品。 因此,我们可以推断出一些主要原则,以改进该特定领域的用户指南。 有了适当的文档,产品就会得到更好的采用,从而不会在客户留言中泛滥技术支持; 对业务的总体影响严格是积极的。 进一步,您会发现一些建议,可以帮助您创建高质量的API文档。 这篇文章详细介绍了如何组织API文档的技术编写过程,如果您正在寻找有关API用户手册中应包含的内容的指南,请参阅此博客文章。 让作家写作 我们已经解决了这个问题。 专业技术作家会创建最佳的用户手册,因为这是他们的工作,并且他们拥有正确的工具,并且对帮助创作过程有更深刻的理解。 但是,API是一个难以描述的主题。 它附带了您应该知道的所有术语,例如端点,方法,请求,JSON,Git等。因此,开发人员发现自己编写文档更加容易,因为技术作家似乎资格不足或不完全了解该主题。 让开发人员创建API文档似乎不太麻烦,但是将来会付出很多代价。 如果用户在理解如何使用产品时遇到问题,那么产品的好坏并不重要。 因此,很明显,技术作者应该创建API文档,但是考虑到复杂性,我们如何安排呢? 双向合作…

可发现性危机以及如何解决它

由于缺少一个单一的中央存储库来收集各学科的学术论文信息,因此很难估计每年出版的期刊和论文的确切数量。 Lutz Bornmann和Ruediger Mutz在他们2014年的论文《现代科学的增长率:基于出版物和引用文献的数量的文献计量分析》中进行了保守的估计,他们在其中追踪所有材料-论文,书籍,数据集,甚至网站。他们引用了1980年至2012年之间的数据。由此,他们对数据进行了绘图,发现科学产出的比率每年以8-9%的速度增长,这意味着总产出每九年翻一番。 (近年来的下降似乎可以归因于没有足够时间被引用的最新论文) 从1650年到2012年,每年被引用参考文献的数量增长(Bornmann和Mutz,2014年) 诚然,这是一个不完善的措施,因为它会忽略所有从未引用过的资源以及不再引用的所有资源。 尽管如此,至少在表面上看来,当前创建的研究数量急剧增加。 甚至这也可能低估了所产生的潜在有价值工作的实际数量。 一位学者估计,每年在他的学科范围内撰写10,000篇论文,这些论文争夺约2,000个篇幅。 那些被拒绝发表论文的人不仅会放弃,而且会继续尝试在其他知名来源发表论文,从而导致积压,使拒绝率达到94%。 由于似乎很合理的理由是,那些未发表的论文中的很大一部分实际上可能是有价值的,并且仅由于空间不足而被漏掉了,因此他主张“创造更多的期刊空间(也许是我们现在的三倍) ),以发表其他论文”。 而且,这甚至都没有考虑到开放访问运动的影响以及直接在社交媒体和网络上共享结果的趋势,以及缺乏传统看门人的方式几乎肯定会增加产生多少内容。 这些讨论对出版商的意义在于,将需要对大量研究成果进行高效筛选,因为如果能够找到相关的工作,那么增加多少无关的材料就无关紧要了。 换句话说,可发现性将成为越来越紧迫的问题。 我推测,如果我们要处理此问题,则必须进行两种技术更改。 首先是内容的细粒度标记,这将使研究人员可以对他们感兴趣的主题进行难以置信的精确搜索。例如,这可能意味着,与其解决几个关键词以及标题和作者信息,书籍将必须提供章级标记,以提供更多元数据以及更精确的元数据。…

技术无纸化学习

它正在逐步稳定地取代传统的粉笔和口语教育系统。 因此,它在教育系统中的使用将使并确保儿童的创造性思维和个人思维。 传统的教育制度或多或少是威权主义的,在授课阶段有一位老师具有所有的至高无上和权威。 另一方面,处于接受端的学生除了接受对他们的教导之外,在整个教学过程中完全没有任何作用。 这种方法倾向于限制儿童的独立推理和判断力。 这导致不鼓励孩子向老师提问和反问。 为了使常规课堂教学本质上具有互动性和协同性,该技术发挥了重要作用。 它确保在老师和学生之间以他们各自的理解来给予和接受知识。 充满争议的学习环境是班级健康的标志。 这可以通过在学习过程中灌输技术来实现。 通过在教学过程中注入技术,学生的学习能力大大提高。 因此,通过在学习过程中的使用,孩子获得了自主学习的自由。 借助技术,孩子可以轻松查询Google并获得激发他/她兴奋的详细信息。 诸如人工智能(AI),机器学习和无数教育软件之类的技术正在改变和改造教室和教学技术。 通过适当使用,可以采用适合孩子的独特和独特的教学风格。 每个孩子都有不同的学习技能和节奏。 传统教学无法解决每个孩子的不同需求,但是技术可以巧妙地满足这种需求。 因此,它将为每个孩子带来个性化的学习。…

没有像计算怀旧那样的怀旧

我希望我能保留我的橡子原子 我1980年12岁的时候,我学会了在Acorn Atom(英国的微型计算机)上用BASIC编码。我的头并没有真正切开)。 开启机器的所有12KB荣耀(以及便携式黑白电视和盒式磁带录音机),并看到光标等待我的命令,这是一次强大的体验。 但是,为什么今天从我的职业生涯起就没有这种经验呢? 在汇丰银行技术领导团队中,我们认为,无论他们在公司中有多资深,每个人都应该保持亲身实践。 我们还意识到,企业IT团队并非总是如此:多年以来,高级人员越多,他们与技术的距离越远,他们越专注于人员,财务和流程的管理。 我们意识到,这与我们大多数专业人士一样适用。 在我们正在进行的重新发现技术根源的运动中,我们最近进行了一次简单的练习。 我们都共享了我们的第一个命令行体验(CLE):第一次我们将(任何形式)的指令输入到计算机(任何形式)中并使其执行某些操作。 我们分享了第一次CLE发生的年份,当时的年龄,所使用的机器以及所使用的语言。 我的第一个CLE是我在上面描述的那一刻:打开微型计算机,它将占用我接下来几年的大部分清醒时间。 在二十一个人(这是一家大公司的大型技术领导团队)中,我们得到了一些有趣的结果。 形成性计算体验普及 首先,每个人在生活中的某个时候都有CLE。 这有点令人惊讶,因为该团队包括来自法律,审计,人事,通讯和财务部门的人员。 但是很高兴发现每个人的某个地方都有合适的技术人员。 其次,尽管经历涵盖了很长一段时间(从1976年到1991年为25年),但是大多数人的起步年龄是相当稳定的。…