Proposal to establish a tutorial style guide

[JStech]

I propose we establish a style guide for the actual tutorial content, to promote a consistent appearance and guide contributors when adding new content. Although code style guides are plentiful on the internet, I didn't find a text-about-code guide to adopt and adapt. So instead, I looked through three core tutorials (Getting Started, MoveIt Quickstart in Rviz, and MoveIt Setup Assistant) and put some initial guidelines together, which I included below. There's probably more to add and change, but I think something of this sort should go in a top-level file, named STYLE_GUIDE.md or something like that.

MoveIt Tutorial Style Guide (Proposed)

• ROS versions: plain text, capitalize version, ROS is optional (also capitalized, of course)

  • If you are using ROS Noetic, be sure . . .

  • This package has been tested in Melodic, but no earlier releases.

• Shell commands are formatted with code blocks (even if a single line), and never with a "shell" prefix like $, which makes it harder to copy-paste commands into a terminal

sudo apt install ros-noetic-franka-description

• Branch names are formatted as inline code

  • Pull melodic-devel . . .

• Proper names of software packages are written in normal font, capitalized appropriately. Only use CamelCaseNames if the package actually uses that name (MoveIt Setup Assistant, not MoveItSetupAssistant)

  • MoveIt, MoveIt Task Constructor, MoveIt Servo, etc.

• "Code" names of packages should be formatted as inline code

  • Many of the tutorials use moveit_visual_tools to step through a demo

• Filenames and partial filenames are formatted as inline code

  • add the previous command to your .bashrc

  • as defined in the .srdf file of the robot.

• GUI elements
  • Large items (windows, panes, sections, etc.) use normal font, capitalized to match the element, with quotes
  • Small items (labels, button text, etc.) use bold font
  • Text the user enters into the GUI uses code formatting

  • Press Ok.

  • In the "Global Options" tab of the "Displays" subwindow, set the Fixed Frame field to /panda_link0

[welcome[bot]]

Thanks for reporting an issue. Because we're a volunteer community, providing a pull request with suggested changes is always welcomed.

[felixvd]

I think those are all fine (although the GUI elements section could use some examples), but should we say something about other than formatting? E.g. "Explain concepts briefly first, then provide examples", "Avoid overly complicated code", "Use 'you' instead of passive voice", "Use present tense"?

[JStech]

That's a good point. Maybe we have sections: Formatting, Structure, Voice

[v4hn]

@JStech This reads good to me, though I'm not sure our current tutorials all adhere to it. :) Could you pour this text into a pull-request for a STYLE_GUIDE.md, as you proposed?