React-beautiful-dnd: Docs ❤️ or 💔?

[alexreardon]

The documentation for this library is great but can be a bit hard to digest. It contains a lot of information and can be a bit daunting for new comers. There is a mixture between philosophy as well as api explanation which might be a bit much for everyone. I am considering writing a stand alone documentation site to help improve this situation. At this stage I have not thought too much about this and I am keen to get the opinions of others in how to move forward. Perhaps what we have now is good enough and a full site is not warranted... I am keen to get your views!

Some things that could be nice to have

• working examples within the documentation itself
• a 'quick start' guide
• a landing page that shows off some of the core features

If we did move forward there would be some technical decisions. My thoughts on those:

• The site should be super simple to create and modify.
• The content should be markup based

If anybody has had positive experiences with a particular library or technique then that would be great to know about

[on3iro]

I think standalone docs could be helpful. Until that point is reached a table of contents could be added to the current docs, so that specific entries are easier to find.

Regarding the tech for external docs a static site generator like GatsbyJS might work well. Unfortunately I don't have any experience with said tech myself.

[LeeHyungGeun]

Standalone site makes the library come into wide use. Also, the quick start and demos will be much helpful to understand than well-written documents. Furthermore if your mother language is not English.

I hope the shows off will be provided with a web JavaScript debugger like JS Bin. For example, KnockoutJS, and on the its standalone site, there are live examples and demos. Because of it, I could start using Knockoutjs easily.

In addition, I am interested in making a Korean version of its.

[jaredcrowe]

Definitely think a table of contents would be a good start - that README's getting pretty long 😅

[alexreardon]

Agreed @on3iro and @jaredcrowe. A good place to start is to add a table of contents to the readme. That will also help layout the content in more logical sections which would be helpful if we did move to a stand alone site

[flipchart]

I think that splitting out the examples into .md separate pages, or having an examples folder with the files ready to run and a .md explaining would go a long way to easing people in. I know I, for one, learn by example, especially before reading all the API docs.

[alexreardon]

To start with I think it would be good to split the documentation down into seperate markdown files rather than having one super file. This breakdown would also be helpful in moving to a stand alone doc site.

[alexreardon]

Proposed structure

landing (readme.md: link to examples, feature set)

• installation and quick start
• design principles
• drag sensors (information about the various types of dragging)
  -- mouse dragging
  -- keyboard dragging
  -- touch dragging
• API
  -- DragDropContext
  -- Droppable
  -- Draggable
• Other (better name?)
  -- Flow and TypeScript
  -- Supported browsers
  -- Engineering

[heyunjiang]

@alexreardon hi, have you finish a 'quick start' guide, i am looking forward to this

[alexreardon]

@heyunjiang I did not realise people where interested in it! Good to know

[Shawn-Williams]

I was able to grok the documentation for the most part by cross-referencing the code in the example provided. There were a few things that were a bit fuzzy for me, but I was able to get through them with a bit of trial and error. I hadn't yet looked a the issues but was thinking that a step-by-step quickstart would really be beneficial. Great work by the way! Thanks to this library, I now have mobile friendly dnd functionality in my new React portfolio project!

[alexreardon]

For sure @Shawn-Williams - a quick start would be really helpful

[adeshas]

a simple sample codes of multiple lists in Board in addition to the sample code in docs #164

[philest]

Agreed. Having the code for the examples would have been hugely helpful. I would make this high priority.

[ajay-gandhi]

I think Read the Docs would be a good place to host standalone docs - I'm all for centralizing documentation in one place.

[gpmcadam]

2¢ from someone new to this library: been trying to get started with this library for the past day or so, I would recommend completely rethinking the documentation and examples given.

The Storybook examples are basically impossible to decipher in any meaningful or simplistic way. And the "Getting started" guide is unreadable for me, so much so that I've decided to look at other alternatives (Shopify/draggable is a great example of something which is beautiful and easy to get started with, I would look to that repo for inspiration.)

Best of luck.

[philest]

Strongly agree with Gary on this!

On Thu, Feb 1, 2018 at 6:07 AM, Gary McAdam [e-mail]
wrote:

2¢ from someone new to this library: been trying to get started with this
library for the past day or so, I would recommend completely rethinking the
documentation and examples given.

The Storybook examples are basically impossible to decipher in any
meaningful or simplistic way. And the "Getting started" guide is unreadable
for me, so much so that I've decided to look at other alternatives (
Shopify/draggable https://shopify.github.io/draggable/ is a great
example of something which is beautiful and easy to get started with, I
would look to that repo for inspiration.)

Best of luck.

—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
https://github.com/atlassian/react-beautiful-dnd/issues/163#issuecomment-362233660,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AG1xBE00CEDEIw1emkSvAopjKWk8GSPyks5tQZrfgaJpZM4QSlkG
.

[alexreardon]

I agree also! Right now we are focusing on building some core functionality. After that lands I hope to give the docs some more love

[sudeepmandal]

I agree with @gpmcadam. This library looks awesome, and I'm keen to give it a whirl, but I've spent a good chunk of time trying to parse through the current docs and the examples and it has been a very frustrating experience. My suggestion would be to have some actual "simple" examples and a quick start section because the current example that is supposedly simple is far from it and has way too many nested components mixed together with styled-components that just makes trying to grok things that much harder.

All that being said, keep up the awesome work. I know how much more fun working on new features is compared to writing docs so it's understandable that the docs are in the state they are in at the moment while you guys are busy implementing a bunch of features.

[alexreardon]

I agree! I am keen to tackle this soon

[alexreardon]

I am hoping to take a look next week! 🤘

[imwtr]

yep, I read around the doc, but don't know how to get it worked in my project...

[alexreardon]

We are moving to a stand alone website: #343
We are creating a quick start guide: #363

I'll close this issue as it was the catalyst for those