These are chat archives for ractivejs/ractive

19th
Nov 2017
Cerem Cem ASLAN
@ceremcem
Nov 19 2017 12:45
How about forgetting about adding examples to the documentation and let the unit tests appear as examples in the documents?
Cerem Cem ASLAN
@ceremcem
Nov 19 2017 12:53
benefits: 1: examples have to be up to date always, 2: this will reduce the effort for the documentation
Joseph
@fskreuz
Nov 19 2017 15:16
Hmm... RxJS does that. I personally don't like it tho. Also, unit tests aren't always written in a way that's fit for examples. For instance, the parse test is a test loop against a json file. Some tests test exceptions and edge-cases which aren't really meaningful to a user new to Ractive, or just overkill for a regular reader.
In theory, it's great but only if the tests were written uniformly and in a readable manner (probably a future todo item).
Joseph
@fskreuz
Nov 19 2017 15:30
Also assumes the docs are auto-generated from the source and tests. That's also cool, but also assumes that the code is written and stored in a way that allows that (like Java or Drupal, per-class and per method).
Cerem Cem ASLAN
@ceremcem
Nov 19 2017 17:55
not every test would necessarily appear in the documentation, but this proposal requires every example should be generated from the tests (putting every piece of test case might look weird)
Cerem Cem ASLAN
@ceremcem
Nov 19 2017 18:04
as we have some example considerations which requires stripping down the example in order to highlight the important part, the example-from-tests approach might require a little bit preparsing
Cerem Cem ASLAN
@ceremcem
Nov 19 2017 18:15
Documentation is something I need for my own projects in the first place as a developer but I cannot spare time to make that happen. moreover, our code base is evolving quite rapidly so any documentation would be out of date quickly. I don't want to say that I built something great but many (including those) constraints led me produce something like that and I liked the result.
Joseph
@fskreuz
Nov 19 2017 19:20
I was thinking of merging docs into the repo. That way 1.) we can enforce that every change come with documentation at a review level and 2.) it's not entirely auto-generated (although one can easily copy-paste the test into the markdown).
It's already possible with the current state of the docs (mkdocs ftw! :tada: ). It's just a matter of looking into what the possible consequences are before rolling it out in that form.
And there's ractivejs/ractive#3052 that I've been playing with for a while now that aims to get everything into one place. Once that gets ironed out, we can probably also document everything in one place.
kouts
@kouts
Nov 19 2017 19:23
Given the fact that not so many resources (i.e tutorials etc) exist for Ractive I think it's important to have basic examples like the ones that exist now in the docs