31–40 of 59 posts
For example; we have a settings system; all keys are defined as constants in code and they have attributes that clearly describe every aspect which is the used to generate the documentation. If you add a new settings, you instantly write the documentation for it as well; so far, it has worked great and I think this could/should work for other parts of the code as well.
It all depends on what kind of API you're building. If you're implementing a RESTful API, no documentation is needed, as it is "surfable" due to the use of hyperlinks. If you're implemeting an RPC API (which is what most of us are doing), good and up-to-date documentation is key, as we need to document each and every meaningful end-point.
I would not want to code against your API.
It all depends on what kind of API you're building. If you're implementing a RESTful API, no documentation is needed, as it is "surfable" due to the use of hyperlinks. If you're implemeting an RPC API (which is what most of us are doing), good and up-to-date documentation is key, as we need to document each and every meaningful end-point.
> no documentation is needed I would not want to code against your API.
Earlier quoted context omitted.
I find your comment about Rails facinating, as it teaches me a bit about how I'm a Blub programmer. I've tried to learn Rails multiple times and the "generate" and "console" commands have always been a massive stumbling block for me. With ever other language and toolkit I've ever worked with, the tutorial starts with opening up a text editor, writing some code, and producing a lousy, "Hello World" website. With Rails…
I don't think this is about being a Blub programmer. Rails is a complex web framework that is designed to help solve many common problems in web development. Therefore, it has tons of code organized in an arcane way you won't understand until you know what problems it's trying to solve . That's why I always found teaching RoR (or equivalent frameworks in your language of choice) to beginners completely backwards. Wha…
Once they grok a simple Sinatra app, they can move on to Rails, understanding that it's doing a lot of magic, but at least having a grasp of how the magic works.
Earlier quoted context omitted.
> no documentation is needed I would not want to code against your API.
Did you read what I posted? If you're writing a REST API (I advise you to read http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte... if you think you know what REST is) then all you need is an entry point (much like http://news.ycombinator.com ) then everything else should be hypertext driven.
Congratulations, I now have a URL and a JSON file the URL spits out.
I still have no idea what the significance of all the values are. I have no idea what their possible ranges are. I don't know how everything works together.
Edit: Also, that's just GET. If you expect me to poke around with POST to learn how your API works, I will run far, far away.
Earlier quoted context omitted.
I don't think this is about being a Blub programmer. Rails is a complex web framework that is designed to help solve many common problems in web development. Therefore, it has tons of code organized in an arcane way you won't understand until you know what problems it's trying to solve . That's why I always found teaching RoR (or equivalent frameworks in your language of choice) to beginners completely backwards. Wha…
The problem, then, isn't that we shouldn't use complex frameworks like Rails, but rather we shouldn't teach with frameworks like Rails. In order to teach Ruby-based web development to the n00bs, use Sinatra. This forces them to address the Ruby language right away, learn http verbs, learn unit testing (well, if I'm teaching them anyway), learn templates, and learn to organize code from a single file up to a simple st…
> Once they grok a simple Sinatra app, they can move on to Rails, understanding that it's doing a lot of magic, but at least having a grasp of how the magic works.
How the magic works, and why it's needed in the first place.
Any recommendations on good doc frameworks/products? We're about to begin redoing our documentation at print.io. Currently we're using swagger ( https://api.print.io/docs/ ) and "self-documentation" ( http://print.io/api ) but i still find that we have a lot of questions.
I'd rather say an API is only as good as the clients/libraries for it. Having an API is nice, documenting it is nice, but this is not what developers are going to use. If you only publish API documentation, you will end up with tons of half-baked, soon-to-be-unsupported, incompatible client libraries. And until then, people will have to roll their own clients based on the documentation, which is not fun. Nobody wants…
I'm working on integrating Braintree payments into a client of mine. Braintree is a perfect example of this and is a wolf in sheep's clothing, meaning, their docs look great at first glance until you need to get all the way through them. For example, you start reading about how to do A. Half way through, you find out you need to do B. So you look at the link to B which then refers to C but C is A and you realize you'…
It all depends on what kind of API you're building. If you're implementing a RESTful API, no documentation is needed, as it is "surfable" due to the use of hyperlinks. If you're implemeting an RPC API (which is what most of us are doing), good and up-to-date documentation is key, as we need to document each and every meaningful end-point.
I like to make an analogy to RSS: If I told you, "Here's a link to my RSS feed." You wouldn't be mad at me for that, since all you need is RFC 822. By the same token, hypermedia/"real REST" APIs don't have _no_ documentation: they have no _specific_ documentation about _this_ particular API.
Without a foundation in this approach towards building and consuming APIs, "no documentation" sounds like a disaster. And it is, in that context.
