Clean up docs inline with book and contrib project

[zzak]

No description provided.

[rkh]

Maybe that's a bit radical. I would like Sinatra to be largely useable without the book. Anyhow, it's the right direction, but I would like to at least have a list of engines, the methods to call, libs you need, maybe link directly to book articles from there.

[zzak]

Okay, so something like the tilt readme with the list of engines?

I'll see if I can whip something up.

Thanks!

[rkh]

Yeah, and stuff like layout_engine and embedded templates (builder/markaby) should be at least mentioned in the readme somewhere.

[zzak]

Added some new commits to merge:
https://github.com/zacharyscott/sinatra/commit/7c89bb9
https://github.com/zacharyscott/sinatra/commit/c29bdc5

[rkh]

OK, to be honest, I still don't feel like merging that in. Don't get me wrong, I love your book-contrib project and I agree the README is way too long. However, there are a couple of reasons why I don't feel like moving this completely over.

First, the README is currently the API specification required by Semantic Versioning. While sinatra-book-contrib may cover the API, using it as binding specification is a bit dangerous. While maintaining the README to correspond 100% with the latest changes already is a hard job to do, it seems close to impossible to do the same for the book/book-contrib/website. Most Sinatra patches would require patches to or at least a review of book-contrib to ensure we have a correct API specification.

Shipping it with Sinatra will give users the documentation corresponding to the Sinatra version used. While differences in versions may be pointed out in the book or book-contrib, it is not the same as being sure to be running exactly the version described in the README.

Second, people new to Sinatra installing the gem might find it handy to have all the documentation ready on their hard drive without having to search the internet, follow links and such. At least when I started using Ruby, having everything available under gem server was damn useful. On the other hand, I don't think bundling the book/book-contrib/website with the gem would not be considered that useful.

Moreover, it is yet a bit unclear - at least to me - what exactly lies in the future of sinatra-book-contrib. Name and description indicate recipes contributed might eventually move on into the book, and it seems to me that links to it are not to be considered stable (which would be fatal, keep in mind that not all people are upgrading to the latest release). If I am wrong, I'd like to have a better definition of book vs. book-contrib vs. website. Also, if it is not just an easy entry point for contributing to the book, I would really love a name change. Like Sinatra Recipes or something.

Also, we already have plenty of translations available, neither the book nor book-contrib are yet able to integrate the already existing translations without becoming rather inconvenient for Non-English speakers.

Last but not least, I don't think there is any harm in duplicating documentation.

A proposed solution: Keep all API documentation in the Sinatra repository and ship it with the gem. Possibly move it around. Either into the doc/ directory or embed it inline. While I would love to embed it, translations would again be disadvantaged. I think the issue is somewhat alleviated if you view the README with a ToC (like the one on the website or generated by Yard). Besides the API documentation we need a project page, like the website, for presenting the project, with news, links to everything and so on. Some of it might be moved to the book or book-contrib (like the part about writing extensions, large parts of the FAQ, etc).

For the book and book-contrib - I really would love to see them change. Both of them are currently way to much API documentation rather than tutorials. I would love one to offer a couple of recipes in the style of "here is one issue, here is how you deal with that". I would love most of the stuff that comes up on the mailing list to be covered in there, like, how do I test helpers? What's the best way to set up caching and so on. Rather than having a section about filters, I'd like it to cover problems that can be solved with filters.

One thing I would also love to see, which probably would need a lot of time and sweat to go into it is a proper book. Not that it is printed or anything, but a book you can read from start to end, where there is one example app that gets more advanced from chapter to chapter, covering basic API, best practices and common use cases. Currently we have three places documenting the API in pretty much the same way and just cleaning up redundancies is not the way to go, imho, I'd rather like to see the focus of the book and book-contrib shift.

Also, sinatra-book-contrib.com should really include disqus or something, so people can comment on the tutorials.

Do not take this as a no or even offensive in any way, I really would like to discuss the topic.

[daz4126]

One thing I would also love to see, which probably would need a lot of time and sweat to go into it is a proper book. Not that >it is printed or anything, but a book you can read from start to end, where there is one example app that gets more >advanced from chapter to chapter, covering basic API, best practices and common use cases.

I'd love to see this.

Also - I've been blogging some 'recipe' type stuff over at http://ididitmyway.heroku.com/ would any of that stuff be useful?

DAZ

[gnandretta]

I feel pretty much the same as Konstantin about this.

When I started using Sinatra I needed to answer a lot of questions about things that I never thought of because Rails (or a plugin/gem) was already doing for me (ok, I still do...). So, having something that exclusively address the common problems or situations, like guides or recipes, is, in my opinion, definitely the way to go.

Also, I agree that the readme is not a very conventional one, but I really like to know that everything you need to use Sinatra is in there,

[zzak]

I'd like to keep this discussion focused on Sinatra and the README, with the changes I've commited here. I will say that I agree the book-contrib project deserves it's own namespace, and that the book definitely needs to be reworked as more of a (best practices) guide to using Sinatra.

The README is the first and most important source for documentation on any project, as well as the most accurate source of documentation (next to the source ofcourse). This remains true for Sinatra, and I'm definitely a fan of having the most up-to-date and polished API documentation available right where you can easily get to it.

I think the problem I have, is the README starts to take over where "Sinatra Recipes" or the book can easily take care of, and the API won't determine whether these things change or not.

What I've been trying to do is separate the differences between API documentation, and recipes. Sometimes it's just easier to use a small recipe to show how the API works, and that's legit.. But having an example for every single template engine is overkill, for the same reason Tilt just lists a table with compatible engines.

I'm not sure now that linking from the README to Recipes and Book is the best solution now, considering that these things do tend to change often.. and could be linking to stale docs. However, I'd still like to see the README go on some kind of diet, and see more documentation that is more guide and tutorial than reference be moved to the book or recipes.

I'll be working more on the book to organize the various chapters and filling in the gaps, and with a bit of love I think the recipe's project will work out just great. We're definitely heading in the right direction, I'm just glad there is an active interest in documenting Sinatra and keeping the community strong.

[dropwhile]

I agree that the readme feels a bit long and could possibly be cleaned up a little.

Maybe creating a doc directory like rkh suggested, and moving ancillary (but still important) documentation into there. Things such as documentation for each template engine. That part of the readme feels a bit long and seems like it could easily be split out without causing too much confusion -- in the same way "writing extensions" is split out in the sinatrarb website (aside: would be nice to put that documentation into the docs dir too). I like the cut selection in zacharyscott/sinatra@c088f0124aa79856997def24c89a2ffd70617872 but moving it to a dedicated in-repo document instead of simply removing or replacing it with a link to the cookbook would be a better option in my mind.

That said, I am not entirely sold on the idea. While I feel the readme is quite long, I also really enjoy having all the information in one place and easy to find. When I first discovered sinatra, it was an 'oh neat!' factor.

My concern with having an external project become an oracle for part of the core functionality documentation experience would be a creeping disparity (wording differences, lag between updates of one vs the other) and dispersity (spread out and multiple-site-at-once core functionality documentation experience). I wouldn't be upset with the readme being split into a 'docs' directory, but would be sad to lose the 'oh neat!' factor.

[rkh]

We'll have to adjust the templates sections a bit further, since Tilt 1.3 will introduce fallback support.

[rkh]

I have no clue how to go about generic templating documentation that still covers all bases and does not confuse newcomers.

[rkh]

Another attempt: tilt-1.3...template-docs

[rkh]

I merged in that branch for now. Please feel free to get back to me with feedback, guys.

[burningTyger]

thanks, that looks perfect!