Improve the docs

[be9]

I've seen the acl9 documentation referred to as "confusing" or "don't read the docs, just use the thing".

Currently the only doc is the huge README file. Actually it's more of a description what and how acl9 does. Would be enough for me if I weren't the creator, but... Different people learn things different way.

So, do you see any ways of improving the docs? What are the most unclear aspects? Should it be tutorials, or...?

Looking forward to your comments here.

[HGebhardt]

I think tutorials like the acl9_example project would be a great idea. In my opinion you have to work with acl9 to understand all benefits of this plugin.

[kevinansfield]

A bit of documentation on testing would be gladly appreciated! I realise the basic cases should be pretty simple, but for those new to testing, just working out the required fixtures can be a pretty big stumbling block

[amalc]

Worked for me. Some mulling over a few points but they were obvious given some thought. Nice job!!

[nathansamson]

"just working out the required fixtures can be a pretty big stumbling block"

Yeah that is right :p Well to be real honest, after 2 years (and counting) the documentation didn't seem to have improved by much, and I can't find it out myself.

I know their is https://github.com/be9/acl9/wiki/Tutorial:-linking-object-and-subject-with-HMT but it doesn't tell how to actually use this in your fixtures.

some_user:
    ..
   posts: A, B, C

doesn't seem to do the trick.

[smathy]

@kevinansfield and @nathansamson - the tests have all been overhauled, and a dummy app included now, so it should be very easy to see how to write tests. As stated in the new CONTRIBUTING guide, the entire suite will run now with just a bundle && rake

There are no fixtures, nor any complex/ugly factories, it's just simple models created for you in a migration that's triggered automatically and uses an in-memory sqlite DB, so you don't even need to create the test DB.

I'm leaving this issue open for the tutorial recommendation.

[smathy]

(and yes, I know how stale this is ;)

[smathy]

I've made some small improvements for 1.2, and am now moving this issue to 1.3 to continue with it.