Review and update documentation

[BetsyMcPhail]

The main README needs to be updated to reflect the changes made in #309. Specifically, the advice "Scripts are provided for various CI instances in scripts/continuous_integration." is out-of-date. Other changes or clarifications may be needed as well.

[jwnimmer-tri]

IIRC there was also one small typo recently in one of the docs where the doc said "install_prereqs.sh" but the file was just "install_prereqs" with no extension. It might be worth just doing a top-to-bottom read through and manual test of all examples, as a cleanup pass?

[BetsyMcPhail]

That sounds like a good idea to me. @tyler-yankee was going to look into #266, would it make sense for him to do this task first? Both as a fresh pair of eyes and an intro to drake-external-examples.

[jwnimmer-tri]

Yup, sounds good to me. Learning the current examples will help when making a new one.

[tyler-yankee]

The drake-cmake-installed example points to drake-visualizer as a demo after installing and building drake, but I understand that tool is deprecated. @jwnimmer-tri: thoughts on removing or replacing the reference to drake-visualizer in the README?

[jwnimmer-tri]

The replacement tool would be drake/bin/meldis.

[tyler-yankee]

@jwnimmer-tri: I'm trying to use meldis but the example in the demo, uniformly_accelerated_particle, is not working. I've noticed some earlier discussions that this example was broken and deleted from drake itself (RobotLocomotion/drake#17653). Is this just an error on my end, or otherwise what should be done with this example?

[jwnimmer-tri]

I'm happy to test it myself, and will let you know. It seems like it only exists in drake_cmake_installed, is that the flavor you're using?

[jwnimmer-tri]

Right, it's the RobotLocomotion/drake#17649 train wreck. You can use this change for now to test:

--- a/drake_cmake_installed/src/particles/uniformly_accelerated_particle.cc
+++ b/drake_cmake_installed/src/particles/uniformly_accelerated_particle.cc
@@ -91,7 +91,7 @@ std::unique_ptr<drake::systems::Context<double>>
 UniformlyAcceleratedParticle::CreateContext(const double position,
                                             const double velocity) const {
   // Allocate context.
-  auto context = this->AllocateContext();
+  auto context = this->CreateDefaultContext();
   // Set continuous state.
   drake::systems::VectorBase<double>& cstate =
       context->get_mutable_continuous_state_vector();

That gets it working for me. (I also ran the example with --target_realtime_rate=0.1 to make it easier to see before it goes off past the horizon.)

I'll figure out the right next step for RobotLocomotion/drake#17649. We might end up deleting the particle from DEE so don't worry about fixing its docs yet.

[BetsyMcPhail]

As discussed in the PR #357, there are two follow up tasks: 1. Of all the examples, the only only one that should use /opt is the drake_cmake_installed_apt 2. Use "conditional sudo" calls (#359)