Move docs to gitbook

[kulakowka]

What do you think about creating documentation using gitbook? If you've never seen what it looks like, here's a good example.

You just need to connect your repository and select the folder which contains the documentation.

We have already done this for one project.

[gihrig]

Looks nice, but I would like to see a search feature or at least a searchable format e.g. the entire doc set available as a single html doc.

[mxstbr]

That sounds reasonable, now that I think about it! Maybe it could live at docs.reactboilerplate.com or something? Is that possible?

[kulakowka]

@mxstbr yes, it is possible.

[kulakowka]

@gihrig githook have a search. It's very fast.

[kulakowka]

You also get the automatic creation of HTML, PDF, ePub, Mobi format out of the box.

[kulakowka]

We created it for feathers.js, you can look at this for example: http://docs.feathersjs.com/#feathers

[gihrig]

@kulakowka

githook have a search. It's very fast.

OK, I see it now, yes it's pretty nice 😄 I had to 'search' Cmd-F for the search feature (hate on the 'modern' grey on grey design fashion)

[jaredmorgs]

@samit4me linked me to this issue.

I'm the docs writer for HubPress and have turned the docs for this project into a Knowledgebase.

https://hubpress.gitbooks.io/hubpress-knowledgebase/content/

This book uses lunr as the search appliance.

The advantage with gitbook is that it integrates well with CI. It supports CNAME if you want to use a custom URL and you can even host it yourself completely off the GitBook.com domain using the NPM-based gitbook-cli.

It also supports Markdown and AsciiDoc.

[gihrig]

This is a fantastic idea 🎉

Many times I have struggled to find something in the RBP docs that I knew existed, but did not find easily through the TOC and having no search... I have even resorted to a Google search "search-phrase site:github.com/react-boilerplate/react-boilerplate/blob/master/docs" which works, but is kinda sucky. 😄

@jaredmorgs

have turned the docs for this project into a Knowledgebase.

Did you mean you have converted HubPress docs to a GitBook KB?

Can you describe the process of conversion and maintenance? What impact does GitBook impose on the doc update process compared to GitHub PRs as we are doing now?

Thanks for raising this.

[jaredmorgs]

@gihrig Yes, you're correct. I made the various README docs stored in the HubPress repo into a uniform resource that uses the Every Page is Page One (EPPO) approach. I basically blew them apart and reassembled them into something that was more atomic in structure.

As you suggest, a user will typically google something to find a solution to a problem. EPPO allows a user to discover an entry point into a tool's information ecosystem and then find a path to other related information. It is a way to prevent users hitting an information dead-end.

You can see the HubPress Repo that serves the GitBook here: https://github.com/HubPress/knowledgebase

Because the book is linked to GitHub through the GitBook.com site, any commits to /master trigger a rebuild on the GitBook.com site. This also answers your question about collaboration. Users can fork the docs repo and make changes using whatever editor they like. GitBook offers a really slick IDE for writing GitBook docs, even integrating the push process into the tool.

For the record, the GitBook team are strong advocates for Open Source, and gave HubPress an enterprise license for free. Perhaps they might do the same for react-boilerplate?

It takes a different approach to writing when you are helping your users to solve a problem rather than documenting how a tool or library works. But if you adopt a modular approach to how you write, you can easily include documentation as components. It might also help your other community contributors write more solution-based articles because they can define the general "How to" question and then back it up with "more reading" type of links.

I've also found that when users create issues, it often drives documentation because they ask a question that isn't covered in the docs.

It may be that a Knowledgebase style resource isn't the right approach for react-boilerplate, but a canonical docs site with the ability to scale your docs seems like a logical next step. You could then link users to the docs in the README, and by doing so return these files to what they were originally designed to do: act as a quick start for users.

[jaredmorgs]

Another point is that GitBook is plug-in based, and themable. I'm sure a group of folks with the experience you have could really do great things with a new theme.

[gihrig]

@jaredmorgs Thank you for the write-up!

Sounds like it would require a basic re-format of all doc files.

Now all we need is some community commitment of sufficient time, etc...

[veksen]

Is this still something in the pipeline? I'd like to get involved.

[gretzky]

@veksen do you want to take the lead on setting this up?

[srbala]

I have forked the repo and published docs under gh-pages using gitbook, site is available for review at https://srbala.github.io/react-boilerplate/ repo available at https://github.com/srbala/react-boilerplate/tree/gh-pages. This is my first attempt. If the team likes it, I will make some more adjustments as necessary.

[blling]

@srbala Really great works! I vote for you :+1:

[srbala]

@blling Thank you.

Initially I had some issues directly publishing in gitbook website, so published thru gh-pages.

now it is also available at https://www.gitbook.com/book/srbala/react-boilerplate-docs/details, the landing page which has download option for ebook formats (PDF, MOBI and ePUB) and website available at https://srbala.gitbooks.io/react-boilerplate-docs/content/

Planning to put a cover image in few days.