Hey @Daxter - I've discovered that `docs/3-index-pages` were autogenerated by the code documentation by a `rake docs:build` task.

During the last months, the two versions were slowly going out of synch. I've fixed that, by merging changes done to `docs/` into the source code docstrings. I've also added made `rake yard` execute `docs:build` after it completes, and made the *warning: autogenerated* comment a bit more visible.

I personally think that YARD is the ultimate reference, and having documentation in the source is a good thing - that's why I maintained this task - on the other hand a more generic "user guide" should stay separate as it is. The index pages is where the two things overlap. What do you think? :-)