Tree-seq docs in the SLiM manual need a review

[bhaller]

On another issue, now closed, I wrote:

I also think that a pass over the SLiM manual's chapter 17, with an eye towards adding mention of this and other real-world issues, and adding cross-links into the pyslim documentation, would be a Very Good Idea. I would suggest that you and I ought to do this kind of separately-but-together: do it one subsection at a time, reading and thinking separately and then having a shared-screen discussion and revision of the manual for that one subsection, then moving on to the next. If we do one subsection at a time, we can spread this work over a longer period of time and make the project less monolithic. It feels important to do, though; SLiM users need to know about these sorts of issues, and need to go to the pyslim doc to read about them, and the existing general statement to "Go read the pyslim doc, it's important" is presumably ignored/forgotten by most users.

"You" is @petrelharp :->. #244 should be folded into this issue. @petrelharp do you have cycles free to do this? It doesn't necessarily have to happen for 4.0.1, but I don't want it to be on the back burner forever, either; improving this doc is important.

[petrelharp]

I would like to do this, but have very few free cycles at the moment, as classes are starting soon.

[bhaller]

Yep. #350 is higher priority for now; let's try to get to this one when you have more time. :->

[bhaller]

Hey @petrelharp, what do you think of this issue now? Doing this for the 4.1 release would be nice. It might not require a whole lot of time, if it turns out that the manual already doesn't suck. :-> Maybe this is another possible to-do item for your visit here, if we find ourselves at a loose end. :->

[bhaller]

@petrelharp and I agree that one big thing to do is to move recapitation to the start of the chapter; it should be the foundational technique, used in the other recipes, to avoid problems with simplify() being used too broadly.