search

h6ah4i / android-advancedrecyclerview

RecyclerView extension library which provides advanced features. (ex. Google's Inbox app like swiping, Play Music app like drag and drop sorting)
https://advancedrecyclerview.h6ah4i.com/
Apache License 2.0
5.32k stars 862 forks source link

Documentation? #268

Open guidedways opened 8 years ago

guidedways commented 8 years ago

This is an absolutely marvellous project, but lacks serious documentation / wiki pages. Any plans?

shynline commented 8 years ago

i m very agree

OzTK commented 8 years ago

I thought the same in the beginning, but try to work with the examples. They are very self explanatory and cover probably all the cases. Once you get it to work the the API is easy to use

guidedways commented 8 years ago

We're all developers after all, everything's easy once we look through examples. That's like asking a mechanic to open the hood of a car and reverse engineer the engine to figure out how it's working - it's all easy :)

The point is, no one's got the time these days when you've got 101 libraries out there doing essentially the same thing. This library's far superior but you don't realize this till you learn that it's mainly due to its flexible API. A few steps worth of good documentation saves people hundreds of hours worth of development time and understanding.

OzTK commented 8 years ago

I agree on a good "Get Started" that would guide to a basic working scenario. I don't agree with the mechanic metaphor. The sample projects are here to avoid having to go into the source code to figure out how it works. I think that basically, having a few sections explaining step by step what the sample does would help

guidedways commented 8 years ago

So you've essentially agreed to what I was saying in the first place but then trying to contradict yourself by saying the metaphor isn't applicable, Okay :) Whatever gets us a good "get started" guide!

Like I said - the library is awesome. And you figure this out essentially by trying out the samples. The samples, however, are not that easy to understand, at least the ones that involve dragging, swiping and expanding. They're riddled with "generics" and a whole bunch of abstract classes with duplicate functionality available via implementation of the various interfaces at your disposal (and all that is difficult to understand without an easy to follow guide). I've got like two decades of programming experience on various platforms and languages and I must say I couldn't figure head or tail without actually going into the library's source code and re-wiring it all (mostly in my head). In particular, the EDS sample has a LOT going on, even if you start off with the simpler ones. On my second attempt it took me 5 minutes to follow the code and how the various wrapper adapters work, but the learning curve was very steep.

OzTK commented 8 years ago

I think the reason there is no real documentation is probably a lack of time from the author. Looking at the EDS sample, it looks indeed complicated, way more than the rest (I've only used Swipe and Drag/Swipe). Maybe that would be the one needing a more in-depth guide

shynline commented 8 years ago

yes im absolutly agree . it takes me 2 hour to understand the library . i just saying for new user that dont know how to deal with examples and so on btw its really amazing library and i myself will begin to write a wiki for this library as soon as my current project finish tnk u 4 answer

h6ah4i commented 8 years ago

Hi! Thank you all.

I admit this library lacks friendly and cool documentation 😞

So far I have not tried to create it yet, because it requires a lot of work. However, I know many developers are using this library today, and many question posts are created to the issue page these days. I feel the importance of decent document is increasing day by day... so finally, I decided to create a project and document site.

https://advancedrecyclerview.h6ah4i.com/

This is a GitHub Pages of Advanced RecyclerView. Its contents is just copied from example of the theme for now, but I am going to write them in my spare time.

If anyone can help me, I would really appreciate. Here is a quick guide how to edit the document site.

  1. Install Hugo

  2. Clone gh-pages-source repository

    git clone -b gh-pages-source --recurse-submodules git@github.com:h6ah4i/android-advancedrecyclerview.git android-advancedrecyclerview-gh-pages

  3. Launch server

    cd android-advancedrecyclerview-gh-pages
hugo server
  4. Open http://localhost:1313/android-advancedrecyclerview/ in your browser

Thanks.