Start documenting Pacto

[jmmercadom]

As a Pacto user
I want to have the documentation needed
So that I can easy understand how to use all Pacto features

As a Pacto contributor
I want to have the documentation needed
So that I can understand easy Pacto implementation
And contribute without too much hassle

Let's discuss on the better way to document Pacto for users and contributors.

[jmmercadom]

To understand the internals of Pacto I would suggest to start self documenting code, then extract the comments from the source code to generate some documentation. Possible tool candidates can be found here https://www.ruby-toolbox.com/categories/documentation_tools.
One "nice" example of code annotated is underscore http://underscorejs.org/docs/underscore.html, there is a tool https://github.com/rtomayko/rocco that generates the same style of documentation for Ruby projects.
I just found this project https://github.com/rubyworks/qed/wiki that brings Literate programming for Ruby projects, still I would dig more about the topic before suggesting to use it for Pacto.

[maxlinc]

I'm a big fan of relishapp, which is used by rspec, cucumber, and vcr, among others.

It generates documentation from markdown and cucumber feature files. Needing to write cukes is a deal-breaker for some people, but I find it worth it for the documentation it generates. And obviously you can still keep the majority of your tests in rspec (or I doubt rspec would use relishapp).

Check out the linked examples and let me know what you think.

[jmmercadom]

Let's use relishapp for generate final user documentation. Personally I found RSpec/Cucumber/Vcr documentation not easy to find using relishapp (their built in search tool sucks), but the advantage that I like is that generates the documentation based on the tests =). I believe that the search issue is related with the tool (I hope it will improve), but we can find a way to use relishapp in our favour.

[maxlinc]

Should we close this?

I think we just need to finish #36 (Contributor Guidelines), and make sure the release process includes publishing to relish.

[marcosccm]

Yeah, we can close it =)

[jmmercadom]

That was fast.
Half of the problem was solved with Relish documentation (the documentation for final users).
The other part is documentation for contributors, my suggestion was to annotate the source code, currently the documentation is pretty empty see (here)[http://rubydoc.info/gems/pacto/frames].
What do you think?

[maxlinc]

I'd split them, based on the roadmap proposal I just sent to the mailing list.

I think the relish documentation is needed for users to try Pacto, so it should be in v0.3.0 (Usability).
The rubydoc is more for contributors (or at least advanced users) so it should be in v0.3.1 (Technical excellence).