Improve documentation for RSpec 3

[JonRowe]

I think we need to pay some attention to our docs for RSpec 3, I've heard numerous people complaining about the Relish features and associated README's, which is partly down to how they're structured, that they don't explain things well enough or that they're just impossible to find (SEO etc)

For example, searching for 'expect rspec' to work out how the new syntax works brings you:

Where as a more relevant page (which the person talking to me eventually wanted) https://www.relishapp.com/rspec/rspec-expectations/v/2-14/docs/built-in-matchers doesn't appear. Even then that page could use some polish to be readable and help people understand the intent...

So I think we need to look at how our docs are structured, wether we can do anything to make them better, and wether we can somehow tune/tweak the search on Relish, or something else...

Thoughts?

/cc @alindeman @myronmarston @samphippen @soulcutter

[alindeman]

I agree. I actually kind of like writing docs (occasionally), so I'm interested in helping here.

I like that we have cukes/relish, but I think we need some other layer of docs that are guided prose and examples. We could use a doctest tool to test the examples if we kept them runnable in isolation.

What are some projects that do docs better than we do? What are some characteristics of quality documentation? What tools should we consider?

[JonRowe]

I'm thinking it'd be nice to have a simple introduction usage page or two, we could use github pages to host it, and then leave the cukes as a detailed overview of features, and RDoc for api docs. I think the key is easing people into finding the right information.

[myronmarston]

We already have rspec.info. We just haven't done much with it. It'd be great to get that improved to the point where it hosts are docs.

[cupakromer]

I'll help on this. I love the Relish docs, so anything I can do to make it better for others :+1:

[JonRowe]

I think we need to turn rspec.info into a "quick start" guide and general overview, with links through to relish for more detailed examples.

[soulcutter]

I like the cucumber features, but I do think there are issues with how they're organized. The most relevant info feels buried, and the least relevant information is near the top. In rspec-core it's (1)changelog (2) upgrade and (3) autotest ?? I literally never looked at those until yesterday. It's not clear to me if it's possible to affect the ordering at all - is there a way, @mattwynne ?

The general pattern most project documentation seems to use is

1. Installation
2. Configuration
3. Syntax
4. Advanced Syntax / Tips and Tricks
5. FAQ

RSpec is a bit different in that Syntax alone covers a lot of ground, but I still think a more-logical progression like that would improve the documentation quite a bit.

I think basic tutorials that link to the documentation would be very helpful. Cross-linking could help some with SEO, and will also help people become comfortable with navigating the documentation.

[mattwynne]

Yes, you can change the ordering using the .nav file. I'm glad to hear people like the Relish docs!

One idea to consider is having another set of feature files that's not the exhaustive test suite, but the user manual. You can publish that as another project on Relish under the RSpec publisher. The advantage of doing that over hand-crafted docs on rspec.info is you'll be confident the examples work because you can test them. Obviously you're still limited to what Gherkin allows though.

If you have any ideas for how Relish could be adapted to work even better for this purpose, I'm all ears. One idea I have is to allow you redirect domains to relish, so if rspec.info did point to www.relishapp.com we'd automatically render the rspec publisher. We could also look at providing custom CSS so you could customise the look of the pages.

[JonRowe]

TL;DR; Whilst I like Relish, I think it isn't suited to the sort of quick start intro we need to help our community get off the ground / find the more detailed docs.

Yes, you can change the ordering using the .nav file. I'm glad to hear people like the
Relish docs!

Well we should look into that, but having three projects here still hurts us, as they won't be unified, most folk do not consider the difference between the projects, they just use rspec. A lot of the queries we get on IRC are about rspec-rails yet people just think it's rspec, and issues get opened on core that could be located anywhere, and this effect extends to confusion about the docs.

One idea to consider is having another set of feature files that's not the exhaustive test
suite, but the user manual. You can publish that as another project on Relish under the
RSpec publisher. The advantage of doing that over hand-crafted docs on rspec.info is
you'll be confident the examples work because you can test them. Obviously you're
still limited to what Gherkin allows though.

The problem with this is it still limits the format. We need to remove the cruft around the simple examples such that it doesn't confuse people, this means we also need to mix up text and code samples. I don't think Gherkin works for us in this respect and from what I've seen of Relish we can't do that, it's text up top and scenarios down bottom and it certainly doesn't allow us to remove the Gherkin cruft around the code. The RDoc stuff on rdoc.info is actually better in this regard.

I certainly don't think we should remove the Relish docs, just create a simpler quick start guide, which we can also use to point to the specific areas in relish for more detailed docs, so that people can find the information quicker.

If you have any ideas for how Relish could be adapted to work even better for
this purpose, I'm all ears.

Have you see @chrismdp's rack-usermanual ? It actively parses the Gherkin into a nicer language, it's not quite enough I think in this case, but if you're looking for suggestions... :)

One idea I have is to allow you redirect domains to relish, so if rspec.info did point
to www.relishapp.com we'd automatically render the rspec publisher. We could also look
at providing custom CSS so you could customise the look of the pages.

Both of those are nice ideas but without greater control over navigation and structure they're just garnish I don't think is needed, Relish looks good, but it's confusing just to it's generated nature and Gherkin parsing, not it's CSS.

@mattwynne I personally like Relish, but I agree with our users that it can be hard to get into, which is partly down to the fact we have 4 projects and partly down to the fact that Gherkin as a language is not suited to pure documentation, it's a specification language that happens to read ok most of the time...

[nyarly]

One thing I keep missing in the Relish docs is reference on how complex metadata matching works - from the code it's ... clear(?) that config.before matches all criteria, and config.include matches any criteria, but since Relish only includes simple examples, I always have to go back to the RSpec code.

[JonRowe]

@nyarly PR's accepted :)

[nyarly]

Not deflected until 3 drops?

[JonRowe]

Master is version 3.0.0.pre so PR's would be merged into it, just not published to relish until 3 hits.

[myronmarston]

We've improved the API docs quite a bit and @mootpointer is working on a new RSpec site to host them. I'm going to close this as the docs will always be a work in progress.

[JonRowe]

Er... I'll ping @mootpointer on this, because he no longer works for Ninefold who were funding him to do organise this...

[mootpointer]

I plan to continue on it.

It's just about ready for a PR.

A. On 20 Mar 2014 19:39, "Jon Rowe" notifications@github.com wrote:

Er... I'll ping @mootpointer https://github.com/mootpointer on this, because he no longer works for Ninefold who were funding him to do organise this...

Reply to this email directly or view it on GitHubhttps://github.com/rspec/rspec-core/issues/960#issuecomment-38144740 .