React Router / History Documentation Site?

[damassi]

I know everyone is working really hard to get React Router 1.0 out and I don't mean to raise a touchy subject, but I wanted to ask if you plan on creating a new documentation site with the release. For people who have used React Router for a while, managing all of the conflicting web references to different versions is manageable (albeit painful), but I seriously pity new users to React or React Router who don't yet understand the concepts or how things should wire together between this library and history and React itself.

Right now, when looking around on the web, there are Stack Overflow issues pointing to other issues pointing to blog posts pointing to upgrade guides and then finally pointing back at the Github Repo to open and closed issues and then to a docs folder which can be very confusing to click through as its hard to see how things relate. I've found looking at the test suite the best approach to see how 1.0 now works, but again, many new users don't know this or are afraid to dig into library code.

I've noticed that between last week and today a lot of the ambiguity has been removed from the API page -- no more TypeScript definitions, etc, and more use-case examples -- so that is a step in the right direction, but nothing can replace a formal docs site. I know GitBook was used for the Redux docs (which are fantastic), and this library was just released By rstacruz: http://docpress.github.io/, also for documentation.

I'd be more than willing to contribute to the documentation effort if what you need is resources, but ever since the documentation site disappeared for History i'm not sure that its even on the roadmap anymore -- hence the reason I'm filing this issue.

[knowbody]

There were couple of similar issues raised already. I think by the time we release 1.0 we will have a website with docs. @mjackson will be the best person to answer this.

[taion]

Could it make sense to make rackt.github.io/react-router redirect to https://github.com/rackt/react-router/tree/master/docs instead of the main repo landing page?

[knowbody]

@taion yeah I fixed it https://github.com/rackt/react-router/commit/a278c97bc50925caedda28759a4cb22a558ec17e

[taion]

:+1:

It's not like the docs went anywhere, everything is still there, it's just organized a bit differently.

[damassi]

I really believe that an excellent library should be paired with excellent documentation, and clear, searchable, pageable documentation makes the burden of answering obvious questions much much less on everyone involved.

Thanks everyone.

[knowbody]

I do agree, I'm not sure if the documentation is lacking anything at the moment. It's more that people seem to like to have the docs on a fancy colourful website.

[damassi]

A fancy colorful website is not about visual presentation, but about understanding how A connects to B, how they flow together within a users active working memory.

Burying documentation within clicks does not help this, and that said I'm not sure that this issue should be closed just yet. See how much information the bottom screenshot communicates?

[knowbody]

cool, I'll reopen. I have it in mind, to make it better.

so is it just navigation? or the content as well. If you can tell what we are missing I'm happy to fix it. The problem is, as I mentioned before, there are issues about the docs, but no one seems to know what they want and what is wrong with the docs

[damassi]

Thanks :) All I can say is that inline examples are the most important, and a clickable API list similar to Redux above or the Backbone Docs, which I've always felt have been top notch in terms of detail and comprehensiveness. Documentation is tricky, but its not insolvable -- just communicate what you know and assume the user is totally new to the system; those are the two fundamental rules.

[zettadam]

Real-life examples go a long, long way. I'd like to see more examples related to larger apps, which I believe is where routers are most likely to be used. There is one, admittedly, but it is not 'huge' and partial loading is not the only thing it should address. There are many concepts that go into a huge app, like Redirect, IndexRoute, IndexLink, HistoryAPI, etc. that have to do with navigation hierarchy and displaying default content.

If the documentation is not clear and easy to navigate and thus understand, many people might not even give this project a pass--it's one of the criteria on many evaluation lists.

[taion]

You can only do so much in examples attached to a repo though. Are there no good real-life OSS examples we can point to? I can't open source any of my projects yet.

[zettadam]

I understand completely. I was only trying to say that good, generic but most common examples (as good as they can get--we only have so little time in a day) is what draws developers to use a library.

[timdorr]

We can replicate the gitbook config from Redux. They can also do some neat stuff like PDF and eBook outputs.

Also, given that @mjackson bought rackt.org recently, we can probably set up a react-router.rackt.org Github page with the gitbook hosted on it. Thoughts?

[taion]

I thought we intentionally dropped the old Gitbook build though?

[timdorr]

It was never gitbook. It was an entirely custom-built website. Gitbook would be a great choice given that it's reliable and pluggable.

[taion]

I stand corrected :smile:

[knowbody]

I'll work on that over the weekend

[mjackson]

In my limited experience with it, gitbook was pretty rigid to work with.

One project that I think has excellent documentation is Electron. Their docs are very thorough, and they even have a style guide for people who want to contribute more docs. I'm not sure exactly how they generate the site, but some pages on the site mirror the markdown files. So there's gotta be a build step somewhere.

[mjackson]

If anyone has other examples of projects that do this well, I'd love to hear about it. We really need something that all rackt projects can use.

@damassi We'd love to have your help if you have interest in helping us with this. In the push toward 1.0, our docs were updated but our site was left behind. I'd love to see if we can rebuild it.

[damassi]

Ok cool. Do you plan on using the same react router site as before or go with a new markdown documentation generator?

[mjackson]

If you know a good one that's already built, let's use that. I'm sure they're out there. If not, we can resurrect the custom stuff we had built. But it will need some tweaking since the docs are in a different format now.

[damassi]

One thing I would say is while the Atom docs are nice, what they're missing is a scrollable sidebar. That's the difference. Often a developer will be looking at the docs and see a reference to another method or component or function, and being able to scroll right to it while keeping the documentation that s/he is currently reading open in order to better understand context is nice. Clicking back and forward breaks working memory.

As far as doc generators go, this seems extremely simple, but that being said I've yet to use it personally: http://docpress.github.io/index.html

[mjackson]

I also saw a project earlier today called gatsby that is a static site generator built using react router. Not sure if we can use that, but would be cool to eat our own dog food.

[damassi]

yeah that's @KyleAMathews's project. Kyle, care to chime in?

[timdorr]

I happen to like how the documentation demo looks. I guess the downside being it's not specifically built for documentation, so other output formats aren't possible.

[KyleAMathews]

Hey folks. I think Gatsby would be a great fit for a documentation site. It uses React Router under the hood as @mjackson mentioned plus is completely built using React components so would be easy for this group to hack together almost anything including live code samples.

Also potentially interesting is Gatsby's support for "starters". These are pre-configured sites you can use as a quickstart. On the roadmap is the ability to build static site "distros" on top of Gatsby. So in other words, there could be a Rackt documentation site distro that you maintain for all the projects here that can be updated and improved independent of each site. So basically create and maintain your own Gitbook.

In this scenario, the "website" would be a directory of markdown and React components arranged in the order needed by Gatsby and your docs distro. Whenever you wanted to rebuild the site (perhaps in a post-commit hook), you'd run something like gatsby build docs/ --distro rackt-documentation-site --publish gh-pages and the site would be rebuilt and published to gh-pages.

Having a high-quality reusable react.js focused documentation builder would be a great boon to the react.js community as a whole as well.

@timdorr there's support for post-build actions where your code is given all your pages w/ their routes. It'd be very possible to write a node.js module which auto-generates a PDF/ebook/whatever.

Be happy to answer any questions you have here and support this effort any way I can! I'd love to see a really robust ecosystem built up around Gatsby! Static sites are awesome and there's tons of potential here leveraging the amazing work being put into React, React-Router, and Webpack.

Pinging @gaearon as he's thought about these issues a lot.

[timdorr]

I'm working on a gitbook branch right now, but it's mostly just a bunch of touchups to the documentation. That should apply to whatever documentation system we use. I'm using gitbook just because it's easy enough to get running on (npm install some things, book.json, and one file tweak), so don't take it as a complete endorsement yet :smile:

[timdorr]

@KyleAMathews I gave gatsby a quick whirl and have some feedback that I hope is constructive.

It appears that most of the magic is inside of the stuff installed into the project when you run gatsby new. That allows for a lot of customization, but it also seems to involve a lot of baggage. Namely, how does one go about updating things as you work out new features or provide bug fixes? There's a lot of functionality contained in userland that can't be controlled by you, so the core CLI could end up breaking compatibility with existing installs. Since you don't have something like NPM to rely on, you can't enforce versioning. That seems pretty brittle to me and will likely bite you as the project grows.

I do like the re-use of existing projects where possible. Webpack under the hood is great and the markdown loader is a smart way to handle it. I'm cool with the metadata contained within the markdown (Facebook does it). But I don't know about the _template.jsx files in there. The idea is to colocate docs on both this documentation site and in the git repo, so having support files in there might be confusing to newbies reading through on Github.

Any idea on how I might be able to set this up in a separate subdirectory (say website/), point to the existing docs files, and get it to build? I tried editing app.js and but couldn't seem to mash the right buttons.

[KyleAMathews]

What's the "magic" you're referring to? I'm not really sure what you're seeing. The only thing that's absolutely required by Gatsby is the loadContext function in [app.js](https://github.com/gatsbyjs/gatsby-starter-default/blob/master/app.js) and the actual content of your site. The plan is to move the require.context into an auto-written dot file. Other than that, there's some requirements around directory structure etc. (some will be made configurable) if you want to make customizations.

What will break Gatsby is changes to APIs in Webpack/React/React-Router as some are exposed to site-builders. Gatsby is on React 0.13 and React Router 0.13 so some projects will see breaking changes upon updating to React 0.14 and React Router 1.0.

re: not including _template files and pulling files from custom directories, these haven't been added yet. This is what's driving the "distro" concept to setup a clean, reusable separation between chrome and content. You'll be able to pull out template code into your Gatsby "distro" and combine that upon building with the markdown and other content.

[timdorr]

I think by "magic" I meant the code in html.jsx and first initial _template.jsx file. That seems like a lot of stuff to throw at the end user after running one command.

What would be neat is packing that up inside a "theme" that you could configure via a .gatsby.toml file in the current directory. There shouldn't be any need for us to maintain the CSS and core layout if you've already got some configuration in there anyways. The less artifacts in our hands and back in your control as a maintainer, the better. You could allow configuration to define override files (hooking into the webpack resolver) or extra CSS files to drop on the page. Optionally, of course, so we don't have to do much of anything.

Basically, I'm advocating configuration over convention. I think that will be less work for you and for users. And don't get me wrong, it's already a pretty killer generator :smile:

[KyleAMathews]

I think we're on the same page here :) My assumption is that eventually that the vast majority of users of Gatsby won't ever touch a configuration or template file. They'll just choose and install their "distro" (or whatever this ends up being called) and then start creating content. The html.jsx/template files are for distro builders and those who want to build custom stuff.

[taion]

Neither here nor there, but I wonder if there's some way we could build a "React Router playground" components into the docs pages that would let people just test out route configurations and links. Would probably have to build something on top of createMemoryHistory for this, but it could be useful.

For React-Bootstrap we've gotten a decent amount of mileage in asking people to produce repros for us based on the component playgrounds on our components page - helps e.g. prune out people who have just misconfigured things.

[damassi]

Thats a really great idea and I think Gatsby could handle this just fine. Given the number of people using React Router, the amount of time it could save would be immense for both the users and the authors.

[timdorr]

@mjackson Electron's docs are built with Jekyll and some scripts to pull from the main repo. So, they would probably be best set up in a separate repo. We could set up a rackt.org repo and build things inside of that. And that would be good no matter what tool we choose, since it will centralize our documentation efforts.

[mjackson]

@timdorr :+1: I think that sounds like a fine idea. If you would like to lead the effort, feel free. @knowbody has also done a lot of thinking about this and work in this area, so you should probably coordinate with him as well. My mind is on other things atm.

[gaearon]

Personally I wouldn't use Jekyll for any of my projects, here's why.

[timdorr]

I'm a full stack dev and I deal with Ruby a lot, so from my perspective the overhead of a Ruby-based project isn't that big of a deal. But I totally get that's my own biased perspective. I think it makes a lot of sense to keep it "all in the family" and set up something Node-based. I'm fine with going with Gatsby, as long as we don't spend too much time fighting it.

[taion]

Relay doesn't use Jekyll BTW. We just do static server-side rendering for React-Bootstrap, but our use case is a bit difference since ours docs are very example-heavy, so the whole thing is written as React.

It sounds like the ideal thing is something that goes from Markdown -> server-side rendered React, possibly with a way to insert actual React code for live examples. Does Gatsby offer that?

[timdorr]

That's a neat setup they've got going on.

Do we need anything server-side? Github Pages can do the hosting for free and allows for an easy deployment process. We could have a separate playground, similar to how Relay does it, but hosted elsewhere so we can deal with non-existent routes on the server with examples.

[taion]

Nope. You just renderToString and put the results on the GH pages.

You don't necessarily need to do the separate playground thing that Relay does. Among other things, the Relay docs pages (like the React ones I think) are actually fully static and don't pull in react.js at all (potentially for browser compatibility?), but I don't see any reason why a general React project's docs site would want to do that.

[gaearon]

FWIW you can take a peek at my React DnD setup which I stole from fixed-data-table.

[KyleAMathews]

@taion Gatsby's MO basically is it takes files (of any type, Markdown, Asciidoc, Latex, JSX, HTML, CJSX, etc) and converts them to pages. Non-react components get wrapped in React components and normal React components are brought through untouched. It then renders those to static HTML files and creates a bundle.js that upon loading, converts the static site into a SPA (using react-router under the hood). It feels a lot like building a normal React website except you get static rendering + Markdown support for free.

[timdorr]

I've set up a barebones repo: https://github.com/rackt/rackt.github.io We can work on stuff in there. Feel free to submit PRs!

[timdorr]

I'm going to close this so we can move discussion over to rackt/rackt.github.io#1.