Failures In Documentation

[mike-thompson-day8]

There's been a recent thread on reddit containing stern criticism of Reagent (which, oddly, started as a rant against OM.Next). https://www.reddit.com/r/Clojure/comments/3vk58p/a_rant_on_om_next/

The most vociferous criticism was from "unknown4242" who was certain that reagent encouraged a ratoms-everywhere, "mutable" architecture - at least that's the impression I distilled from his slightly all over the place rant across multiple comments.

So "unknown4242" has hurt himself using Reagent.

At any scale above the trivial, that ratoms-all-over-the-place architecture will be problematic, and lead to a messy disaster. That's what he experienced.

To me, it seems so obvious that this is a bad idea that it wouldn't even occur to me that anyone would do it. But, after reading his rants, I looked back over the reagent docs and noticed that there is no advice anywhere to stop a person from doing this. In fact, just the opposite, the examples, in attempting to keep things simple, use the multiple r/atoms approach.

So I guess I can understand how an inexperienced person could get the wrong impression. Go in the wrong direction. Hurt themselves.

So this ticket is about us improving the docs. Improving the advice.

But there's a meta level to this ticket ... and it probably needs to be solved first ...

Over time, I've shied away from trying to improve the official Reagent docs because the existing tool chain just doesn't work on Windows (where my clients and I live). I tried putting docs in the reagent Wiki but noone ever found them, so in the end I put my docs into the re-frame Wiki because there they got some exposure. But that's clearly not the right place.

So ...

We need to make the Reagent docs better in many ways - add FAQs etc - but they are currently immutable and incomplete. But, in my experience, that can't happen until the tool-chain used is improved. I have no idea how that should happen. You thoughts? Abandon the existing custom tool-chain and use something more crossplatform like jekyll? Move to something hosted like Readme.io? Other options?

Recent exhibits: #206, #147, #191, #101, etc

[escherize]

https://github.com/tripit/slate Is a good candidate. Slate has pretty good deep-linking and looks.

Although its actually made for documenting APIs, there are people using it for libraries/frameworks.

Some examples: http://developer.aircall.io/#examples <- looks good without language selection http://appium.io/slate/en/master/?javascript#automating-hybrid-ios-apps

[arichiardi]

One thing, don't let the opinion of one influence your good work :) The re-frame doc is one of the best docs I have read in Github. Reagent might certainly add some more about how good is to have a single atom for global state, but as somebody (maybe you?) wrote in the Reddit post, Reagent is so little opinionated than it allows you to employ the architecture you wish. What I mean is, you can't save yourself from yourself.

Second random thought: project's doc should go in Wiki. If people cannot find it, maybe there is a problem with GitHub affordance. To solve this, in replumb I have a doc folder that you can lein codox anytime yourself and reflects the version you are in. This isn't perfect, it mitigates a bit the problem, but it is for API only.

Finally, that's very good that that rant...ehm...feedback will trigger further improvment and I found it positive for ClojureScript in general.

[Frozenlock]

~~I try to use as little ratoms as possible, mainly to keep things simple. However, I won't shy away from spinning new ones to keep local component states. And while many people prefer to use a single ratoms to store data, I'm not afraid to use a few if it means it will make my life easier/simpler.~~

~~I don't think I've ever hit a performance wall because of too many ratoms. I hit other problems before that.~~

~~I suppose a quick mention of performance decrease for X number of ratoms could be good enough. How many ratoms do you need to get a noticeable performance hit?!!~~

Edit: wasn't about perfomance.

Second random thought: project's doc should go in Wiki. If people cannot find it, maybe there is a problem with GitHub affordance.

This. Wiki, every time. A webpage is nice to make demonstrations, but having a wiki editable by everyone is the best way to get the most complete (and up-to-date) documentation. The wiki must also be linked from the Readme; not everyone thinks to check the wiki section of github repos.

[mike-thompson-day8]

@Frozenlock I've seen no suggestion (in the rant or elsewhere) that more ratoms causes performance problems. It is generally cognitive/testing/scaling etc problems (aka architecture problems). And, even then, only as an app gets more complicated -- almost any approach works at small enough scale.

Regarding Wikis - sure, they are okay. Certainly one option. But in my experience they seldom encourage much user content. For example, I went all in with the Wiki on re-frame and, so far, I've got virtually no content provided by others, beyond the occasional typo correction. So I don't find that Wikis are anything magic in terms of encouraging content. In fact, I've had more input on the re-frame Readme which involves people going to the trouble of a PR. And Wikis have the disadvantage of being pretty static, poor content menus, can't include live coding, etc.

But I'm not totally against them. I'd just like to understand all the options (I feel slight under-informed about the options). I look, for example, at http://cycle.js.org/ and wish that reagent had something like that (via Jekyll).

[mike-thompson-day8]

Let me make the initial, meta questions here clearer ...

1. How should we make the docs more extensible and easier to deal with:
   • use a static site generator tool like Jekyll ?
   • use the Wiki
   • use a hosted solution like readme.io (which I beleive is free for open source).
   • roll our own via creating a Reagent SPA (as is currently the case) but move to an easier toolchain. Boot? Lein?
   • are there other options?
2. Who here is interested in contributing an hour or so, to help port existing docs to a new system? Assuming some agreement around point 1.
3. Who here is interested in producing more content? I have a list of things which need to be better explained :-) (Actually I don't but, give me 5 mins and I would).

[gadfly361]

Regarding 1, I don't have a real preference or recommendation (sorry, wish i could be more helpful on this one!)

Willing to help with 2 & 3.

[Frozenlock]

@mike-thompson-day8 You are right, my bad. I read the entire thing, but I somehow got the idea it was about performance and not just architecture.

For something more dynamic than wikis, I've noticed that some people are using devcards:

• https://awkay.github.io/om-tutorial/
• http://timothypratley.github.io/reanimated/#!/timothypratley.reanimated.examples

The downside of devcards, Reagent SPA and Jekyll is that the content isn't immediately editable.

[pepe]

Hello.

1. Reagent SPA, maybe with the devcards, as mentioned by others, will be great, as the docs will be the example in itself. The easier the toolchain (actually, what is current one?) the better. The hardest in my opinion, will be to keep it up-to-date with library. The downside is, that gh-pages must be generated on dev maschine (or CI), but I did it with Middleman (static generator like Jekyll) for some projects and it is not that hard.
2. Here goes my friday afternoon.
3. Here goes my second one.

Just aside, I am using reagent/re-frame for rapid prototyping of the static generated webs to my great pleasure. When prototyped, just connect to data pipes.

[mike-thompson-day8]

@holmsand any thoughts or preferences or suggestions?

[yogthos]

I definitely agree that it would be nice to have more comprehensive docs, and especially regarding best practices. A style guide would be of great help for beginners.

I would vote for using http://cryogenweb.org/ for documentation, it's a Clojure static site generator, so it wouldn't require additional tooling and I think it's flexible enough for anything we'd need. It's also compatible with gh pages.

Since cryogen is based on a lein template, it makes it easy to add stuff like cljs support to the project and then have live docs generated.

I think it's also important to make it easy to contribute to the documentation project. Again, this is where having a lein based project would be nice, anybody who's already using Clojure could just clone it and work on it without having to install additional tooling.

[yogthos]

@mike-thompson-day8 I'd be up for helping with getting a docs system going. It's certainly a pain point for people, the main thread on the new Reagent release on reddit focuses on this being a problem as well.

[gadfly361]

+1 for cryogen - it is really simple to edit and run locally.

[arichiardi]

I was also pointed to https://github.com/hashobject/perun for boot which seems quite awesome as well!

[Frozenlock]

Cryogen seems to be the best solution so far, considering that Reagent itself is using Leiningen. I would also add that being able to run locally, without any other dependency, is a huge advantage.

I should have a few hours available this week or next weekend to spend on this if we get this ball rolling.

[yogthos]

That would be fantastic, and if you find any deficiencies in cryogen definitely open up an issue. The author is very responsive, and I help out with it a bit now and then. :)

[Frozenlock]

I played around for a while in Cryogen, but quickly faced limitations. (Cryogen's documentation website itself is using a custom version of Cryogen.) It looks great for blogs, but doesn't fit quite as well for a small documentation website.

Another disadvantage I found is how to handle demos. One needs to write the Reagent demos and call them from within the markdown files, or include divs with specific IDs and make sure the reagent components are looking for these. The constant juggling between the markdown-clojure and reagent-clojurescript feels a little icky.

I'll come once more forward and propose to use Devcards. http://rigsomelight.com/devcards/#!/devdemos.core

[gadfly361]

I originally gave my +1 for cryogen (which I still love for blogging). However, after using devcards for documenting soda-ash, I agree with @Frozenlock to consider devcards for reagent documentation. In particular, being able to use devcards' mkdn-pprint-source has been really convenient.

[yogthos]

I like the devcards idea, it seems like a great fit for making examples and tutorials,

[mike-thompson-day8]

After a considerable pause, it is time to reactivate the issue of "docs tooling" for further discussion, and this issue is the right place.

Background: recently, we have been accumulating copy into /docs. The README.md acts as something of a "Table of Contents", with each .md holding a chapter. A special thanks to @jmlsf as well as @pesterhazy and @gadfly361

First, please contribute to this important project!! Getting together good explanations, examples and structure/sequencing is critical. It is a credit to Reagent that it has flourished despite having such patchy and scattered docs. Please look at these existing docs and ask yourself "what is currently missing?" What needs to be improved? Can you put together a chapter? A one pager? An FAQ? Can you review what is already supplied? Do you have a better example? Does an existing example need further clarification. Please contribute.

Second, once accumulated, how should this material be packaged up and presented as a User manual. What tooling should be used? This has been discussed before, but let's have another round of discussion because some time has passed.

Just to be clear, the accumulation of good copy is way more important than packaging. So please let that be your main focus. But. A good way of pulling it all together will ultimately be very important too. People do judge a book by its cover. And Navigation and TOC are important. So, yes. let's have that secondary discussion (but don't think that tooling is more important than raw content).

[yogthos]

One thing that's been working well for me is the way I manage macchiato docs. There's a src branch that has the static site template, and it has markdown for the doc pages that gets compiled by travis and pushed to the master branch which is just a github site. Anybody can easily contribute the docs by updating the src branch and changes are immediately propagated to GitHub pages once travis builds it.

My preference would be to use cryogen since it's clj, well documented, and I think would satisfy the requirements here, but I'm open to other suggestions there as well.

[DjebbZ]

Now there's cljdoc.xyz from @martinklepsch, I think relying on it for the rendering is a good idea. Folks would just need to focus on the content.

[pesterhazy]

I've started an experimental branch re-arranging the docs here: https://github.com/reagent-project/reagent/compare/master...pesterhazy:pau/docs?expand=1

Guiding ideas:

• As I see it, the docs are already good, we just need to organize them so people find things, especially the new guides in /doc.
• Organize the documentation into four chapters. similar to how popular projects like Expressjs do it: https://expressjs.com/
• The chapters would be

I. Getting Started
-> Installation and Usage example (This probably needs some work)
II. User Guide
-> The contents of /doc
IIa. Appendix
-> FAQ
III. Api Reference
-> Autogenerated codex docs, i.e. the namespaces section of https://cljdoc.xyz/d/reagent/reagent/0.8.1/doc/documentation-index/
IV. Resources
-> Links to external tutorials, screencasts, blogs and obsolete information (like the NEWS blog posts)

• Use cljdoc.xyz to host all three parts
• Rename the "Tutorials" in doc/ to "User Guide" to highlight the fact that they explain the essential concepts behind Reagent
• When this structure is in place, encourage people to contribute more guides

What do you think?