操作指南(How-To Guide)
操作指南与教程截然不同,因为它们面向不同的受众。操作指南是面向问题 (Problem-Oriented) 的,假定读者来到此页面是为了回答一个特定问题。这些页面具备以下特质:
- 一系列步骤
- 聚焦于目标
- 解决特定问题
- 无多余解释
- 一定的灵活性
- 实用性强
- 命名良好
在教程中,你仔细引导读者完成一系列步骤,目标是学习。跟随教程的读者对术语和概念还不够熟悉,尚无法提出具体问题。而操作指南的读者已经在使用 MoveIt,只是正在寻找执行特定操作的说明。
名称回答用户的问题
Section titled “名称回答用户的问题”操作指南回答非常具体的问题,并且应该能命中用户的 Google 搜索关键词。因此,命名非常重要。好名称的示例有:
- How to Visualize Collisions in MoveIt(如何在 MoveIt 中可视化碰撞)
- How to Grasp Objects with MoveIt(如何用 MoveIt 抓取物体)
- How to Run MoveIt with UR5(如何用 UR5 运行 MoveIt)
- How to Fix a Segfault(如何修复段错误)
- How to Migrate from Foxy to Galactic(如何从 Foxy 迁移到 Galactic)
- How to Run in Gazebo(如何在 Gazebo 中运行)
- How to Set Up a New Robot for MoveIt(如何为 MoveIt 设置新机器人)
- How to Use the MoveIt RViz Plugin(如何使用 MoveIt RViz 插件)
- How to Teleop a Robot Arm with a Controller(如何用控制器遥控机械臂)
聚焦目标、切实可行
Section titled “聚焦目标、切实可行”对于这些指南,重要的是专注于解决用户来到本站想解决的问题。因为这些用户对核心概念已有更深入的理解,所以当需要做出取舍决策时,你应该向用户提供一些选项。你应当在操作指南的引言中说明假定的前提条件。这样既能避免在本站重复说明,也能让已经了解前提条件的用户直接着手解决问题。