wms策略文档_内容策略:技术文档的新理念
wms策略文档
我们是否可以首先同意文档很重要,而我们想要更好的文档呢? 好。 这样一来,我就不必为为什么要关心而写三段式的报告了,这样您就可以保留更多的时间来阅读它会花费您的时间。
为了生意! 作为在企业软件行业工作了近七年的技术作家,我已经看到软件用户,创建者和组织对技术文档的态度发生了巨大变化。 如果在我职业生涯的早期,我被教导要尽可能多地记录文件,那么如今,人们似乎更在乎内容质量而不是数量。
文档,中断
加入Red Hat之后不久,组织变革导致内容服务团队与面向客户的角色(例如技术支持,客户经理和客户体验经理)并肩作战,我们的变革无处不在。
这意味着我们需要认真应对并检查我们所做的事情 ,因为我们现在在我们产品的客户体验中扮演着至关重要的角色。 技术作家不再被我们的工程师所吸引,而是拥有正式的席位和发言权,并负有责任。
我们对如何处理文档进行了深入研究,得出的结论是,接近内容时最重要的问题是:
- 我们如何创建用户实际阅读的有用文档?
- 我们如何将内容创建无缝集成到我们现有的软件交付过程中?
- 我们如何才能使我们的社区以与贡献代码相同的热情来贡献于文档?
当然,没有人会生活在真空中,当我参与开放源代码社区并开始参加技术活动时,我遇到了表达这些问题或它们的某些变体的公司和项目,这显示了使我成为一个普遍趋势的趋势。非常高兴的文档女士。 激动人心的时刻!
在这个由三部分组成的文章系列中,我将尝试巧妙地使用开放源代码社区和Red Hat文档团队的成功文档解决方案的真实示例来回答这些问题。
在第一部分中,我将重点讨论第一个问题,该问题讨论了文档的原理。 然后,在以后的文章中,我将探讨解决文档演变的技术和社区方面的其余问题。
内容策略,技术文档的新理念
让我们看第一个问题:如何为正确的用户创建正确的内容,并在正确的位置和正确的时间将其交付给他们?
如果您熟悉内容策略的概念,您可能想知道它与技术文档有什么关系。 内容策略不是Web设计和文案写作的主要内容吗? 好吧,不再了。 如果我们将文档视为独立产品或软件的交付要求 ,则必须像其他任何交付产品一样计划,创建,交付和管理我们的内容,这意味着需要深思熟虑。
在这一点上,我想向Rich Bowen大喊大叫,Rich Bowen的文章RTFM在Opensource.com上的Doc Dish专栏上发表了文章? 如何写一本值得一读的手册 。 他谈到了这种预见性的几个关键要素,我将在本文中对此进行扩展。
先问,以后写
内容策略的核心完全集中于内容的用户(读者)。 当我们记录特定的功能,组件或用例时,我们必须了解我们的读者。 在不尝试原创或重新发明轮子的过程中,我将使用著名的五个W来解释这一思考过程。
我的读者是谁?
正如Bowen指出的那样,创建有用内容的第一步是找出我要写的人。 我是在为最终用户,开发人员,业务分析师或系统管理员写作吗? 我的用户是初学者还是忍者书呆子?
能够确定读者的角色( GNOME帮助登录页面就是一个很好的例子)为您提供了基础,以构建对这些用户有用的内容。 现在,您可以在某些假设条件下询问其余问题,这些假设是关于读者已经知道的,他们的想法以及最有可能吸引他们的内容。
我的读者想知道什么?
这个问题不仅可以揭示读者想要的信息类型,还可以揭示我应该使用哪种格式来传递信息。 例如,当我面对在OpenShift Enterprise上为JBoss Fuse编写部署指南时 ,我必须真正专注于最小量的内容,这些内容将帮助新用户入门,而又不会向他们灌输他们所拥有的所有很棒的东西的信息。可以使用Fuse或OpenShift。
相反,如果要为开发人员创建命令行工具或库,则该工具提供的所有命令和选项的完整参考是产品用法的自然扩展。 是的,手册页可能是交付此类内容的最佳方法。 没有什么比奔跑的人[COMMAND]的乐趣大,并且可以找到很好的选项描述和示例。
我的读者何时需要此内容?
这个问题是紧密联系在一起的后续哪里的问题,有时答案可以覆盖这两个问题,但是当独立解决,答案可以在软件使用或贡献我的读者很可能这一点透露给需要的是我的内容写作。
这意味着,如果您正在为Arch Linux之类的uber-ninja开源项目创建内容,则可以猜测读者已经尝试解决他们的问题或独立实现目标,因此当他们寻找文档时,不仅沮丧,而且已经知道他们在寻找什么。 在这种情况下,Wiki站点是无需强大的搜索功能就可以启用强大的搜索功能的完美方法,因为没有人有时间在这里浏览!
优点:在这一点上,您还可以开始考虑发布和整理内容的频率。 版本发布后,我的读者需要立即了解哪些信息? 我们什么时候可以终止(早期版本)早期版本软件中的内容? 等等...
我的读者在哪里消费此内容?
还记得我在什么问题中提出的手册页吗? 这是有效放置内容的一个很好的例子,在这种情况下,就在终端中。 同样,当您交付IDE或桌面应用程序时,嵌入式或上下文相关帮助可以改善或破坏用户体验。 对于您的GitHub托管项目而言,良好的README主页的重要性几乎已经确定。
可以使用Sphinx自动文档和JavaDoc之类的工具轻松地从代码中自动生成API引用,仅举几例。 投资于人类可读的代码注释不仅可以为您的用户提供帮助,也可以为需要从现在起六个月后更新代码的任何开发人员(包括编写它的开发人员, 让我们面对现实 )提供帮助。
此外,错误消息。 他人不会发生任何事情,翔实而清晰的错误消息可以使用户免去对文档库的访问,因此没有理由不将其视为可在问题发生时立即向用户提供信息的正式内容类型。
为什么我的读者需要此内容?
这个问题可能是所有问题中最棘手的问题,因为它使您的内容的目的受到WIIFM (对我而言有什么意义)测试的审查:您为什么还要编写此内容? 您为读者解决的是哪种痛苦? 他们为什么会关心您在写什么? 我知道,有很多难题需要回答。
如果我们回到读者在文章开头问过的问题—关于您是否同意文档很重要的问题—如果我(和我)不会花时间和精力写这篇文章。来自Opensource.com的聪明人)认为这对您没有用。
请记住,您正在阅读本文的目的是学习如何改进文档,如何社交化组织中的哲学变革,或者只是为了确保您并不孤单地以这种方式思考,我将试图以最有效的方式来构建这篇文章,并希望我能引起您的兴趣,使它到最后。
伟大的理论! 但是如果...
没错,我刚刚描述的方法可能与您的组织或社区如何查看和处理文档相距甚远。 我不会假定所有答案; 我能给的最好的建议是从小处着手,看看进展如何。
因此,如果您的公司雇用了几个技术写作团队,请与其中一个团队一起运行POC(概念验证)。 保持同事进度的最新进展,并记录所有发现和过程,供其他人选择采用此做法时使用。
如果您的开源项目缺少技术写作专家,请联系其他社区寻求帮助。 协作是开源软件的Struts之一,没有理由不集中我们的智力资源来创建每个人都可以受益的更好的文档。
自从我们在Red Hat开始这一旅程以来,我们在理解用户方面已经走了很长一段路,并且取得了可观的进步。 我们甚至有文档的内容策略师,扮演文档产品经理的勇敢者,并对内容进行重要的分析和分类,以便我们可以将精力集中在人们实际阅读的内容上。
当然,哲学的改变仅仅是开始。 在下一篇文章中,我将尝试解决成功文档的技术方面。
剧透:涉及DevOps 。 (提示不祥音乐)
碟
本文是Rikki Endsley协调的Doc Dish专栏的一部分。 要撰写本专栏文章,请提交您的故事创意或通过open@opensource.com与我们联系。
翻译自: https://opensource.com/business/15/6/documentation-content-strategy
wms策略文档
wms策略文档_内容策略:技术文档的新理念相关推荐
- sphinx 编码 php文档,用Sphinx编写技术文档
用Sphinx编写技术文档 大家会发现,如果一个项目主要是用Python写的,其文档都很类似,比如:Python在线的HTML官方手册.这些项目的文档都来源于一个很不错的项目:Sphinx.这个Sph ...
- 关于我为了看懂技术文档而爬英语技术文档的单词这件事
想法来源 之前,应该是看了<大话设计数据结构>作者在书中说过(应该是这本书名,如果不是,抱歉,我没记名字的习惯),为了逼自己学英语,爬取英语网站的单词,把英语网站常用的单词,按出现的次数排 ...
- 如何在Word快速合并多个Word文档的内容到一个文档中
如下图所示,将多个Word文档中的内容合并成一个文档. 如何操作? 请继续往下看详细步骤: (1)打开一个空白文档,或指定一个文档,点击[插入]-[对象]-[文件中的文字]. 选择要合并的 文件夹内容 ...
- mysql导出表结构word文档_如何将Word文档导出为长图片格式
如何对word文档转化成潮图片格式呢?给大家分享一下,将word文档转化成图片具体方法,对大家能有所帮助. 方法/步骤 1 首先,如果想将word文档转化成图片格式文档,我们可以直接用word程序来实 ...
- java 自动生成文档_[原]java开发文档的自动生成方式
对于Java注释我们主要了解三种: // 注释一行 /* ...... */ 注释若干行 第三种,文档注释: /** ...... */ 注释若干行,并写入 javadoc 文档 通常这种注释的多行写 ...
- java非主流火星文输入法_我爱火星文_火星文输入法
火星文输入法是一款火星文即时转换软件,包含火星文转换器和繁体字转换器,支持非主流火星文转换,繁体字转换,菊花文,QQ闪字,在线转换兼容所有中文输入法,是新新人类QQ聊天的必备工具. 火星文输入法,是2 ...
- 朋友圈产品文档_企业微信上线朋友圈等新功能,超250万企业接入企业微信
12月23日,企业微信团队宣布在最新版本中升级群聊功能.开放客户朋友圈内测以及推出高效协同工具套装等重磅能力,进一步强化企业微信与微信生态互通能力. 腾讯微信事业群副总裁黄铁鸣介绍说,目前企业微信已经 ...
- windchill 可交付成果 文档_敏捷等于没有文档吗?敏捷项目管理VS传统项目管理区别在哪里?...
前阵子,一个负责产品开发的负责人跟我说,他对正在进行的产品交付项目的要求是:能够在短期内看到成果:可以随时快速地了解项目进展:不需要那么多"没必要"的设计文档,却迟迟看不到交付的功 ...
- iap 审核 文档_为什么必须审核文档
iap 审核 文档 如果您向一群人询问好的文档的质量,您可能会得到许多不同的答案,但是准确性和易读性应该在每个人的清单上都很高. 您的文档很可能100%准确,并且在发布之日就非常容易阅读,但是随着它们 ...
最新文章
- centos7 安装apache+php+memcache
- 运行webpack-dev-srerver 端口占用错误及解决办法
- 阿里云学生计划领取攻略
- usb4-配置usb触摸屏
- P2607-[ZJOI2008]骑士【基环树,树形dp】
- 高级 Java 必须突破的 10 个知识点
- Java 8的方法参考进一步限制了重载
- java cron工具类_Java工具类之:包装类
- Vue基础之Vue列表渲染
- supervisor安装和配置
- java 提取电话号码_java – 如何使用正则表达式提取字符串的电话号码?
- 怪兽充电宝 共享充电宝源码
- 我逛了下 JDK 一条街,发现了不少好东西!
- 2021年信息学部物联网工程学院学生科协第一次Office大培训
- mysql查询父子关系树_根据数据的父子关系创建树形结构并实现遍历
- 基于Multisim的波形发生器
- “燕云十六将”之Grace陈敏(9)
- 论文-Interactive Path Reasoning on Graph for Conversational Recommendation
- USB设备被识别流程
- 亚马逊测评系统软件搭建教程:luminati+候鸟防关联浏览器环境