Documentation Opinions

[BryanGrezeszak]

Currently the Reflux documentation is mostly about the original API with the ES6 type usage at the bottom, sorta out of the way.

I'd like opinions on whether this should be changed.

And, if so, what the severity of that change should be.

• Change nothing about the general structure of the docs?

• Make ES6 usage the main point of the docs, and include an "Original API" (or some title like that) section?

• Make the docs totally about ES6 and include a separate markdown file for the original API for those that want it?

Aside: it would pretty much just be the store/component parts that would change. Actions are basically unchanged anyway and so the docs for them would stay as-is with any of the above options.

Personally, my opinion is that if Reflux is gonna survive we pretty much need to go full-bore modern with a vengeance as quickly as possible: so the third option. That way only 1 API is presented at first glance, and it's the one that works with the newest proper way of doing React. The original docs would still be there, but you'd click to a different file to view them so that no confusion would arise as to why there's essentially 2 different sets of docs on the same page. But I want opinions.

[eek]

I would go with making the docs totally about ES6 and a separate markdown for the original API. Classes are the newest and proper way of doing React so I would go with that. With what can I help you on the docs side?

[esbenjuul]

I agree the documentation should be focused on how to use it the ES6 Way. Maybee make some new examples of how to use the API and re use the existing docs that Way.

[spoike]

I'm okay with it being the ES6 way (since for React is either that or the pure stateless way). I think most of the examples could be moved over to a separate markdown doc not to detract beginners since the README has grown verbose with each new feature that was added to Reflux. If someone in the community wants to help out then please do.

[BryanGrezeszak]

@spoike - I like the idea of getting the docs smaller too. Maybe the main README provide for basic usage, and the separate markdown docs for more advanced usage of each feature.

[eek]

And I think we should also update the CHANGELOG.md :-s

[BryanGrezeszak]

@eek - the reason I didn't do any changelog stuff on my previous updates was that it, unfortunately, had already been abandoned and wasn't up to the newest version as-is.

But I'll try to just gloss over the missing v0.4 stuff and at least give the basic idea of what's new in v5 though. From there we can re-animate the changelog from the dead, hopefully.