Proposal #10 - DevPortal Documentation Update - One Pull Request

in steemdao •  4 months ago 

This week, I only have one new pull request for Steemit, Inc. to merge:

  • PR#425 - New Recipe: API Pagination

This one was particularly time consuming, partially due to the amount of reverse engineering it takes to track down that one field name in order to accurately document it. Sometimes, all I have to go while looking for a method argument is "What does the method argument look like?" (hint: not Marsellus Wallace). Ok, it looks like a timestamp. This object has five of them. So which one? It also depending on who you're talking to, steemd or hivemind.

Anyway, what this recipe does is explain the various forms of pagination solutions. I've grouped them by namespace, which should give the reader a pretty good idea of how they all should work, once you realize that methods in the same namespace work about the same (pretty much):

https://inertia186.github.io/devportal/tutorials-recipes/paginated-api-methods

But there are tiny/subtle differences, even within the same namespace (also depending on steemd or hivemind). Like how one method doesn't allow you to select an order and another method not only lets you select an order, but also a direction. Or how usually the limit is 1,000 objects but once in a while it's not. This is not a critique. Instead of just complaining about the subtle gotchas, I'm just documenting them.

For this reason, I've iterated each method and order type, which may seem like overkill. But I'm approaching this from the standpoint of someone who doesn't know the patterns (or thinks they already know the patterns). They only have one problem to solve from one method they want results from. In that situation, they're going to look for that specific method and not bother with learning the overarching pattern. Why should they? Especially if that pattern doesn't apply to all methods exactly the same.

Welcome to the Steem API. 😂

Authors get paid when people like you upvote their post.
If you enjoyed what you read here, create your account today and start earning FREE STEEM!
Sort Order:  

The sparse documentation is a real problem with Steem. Even the APIs that do the RPC calls for you like (steem-js). I think it shouldn't be such a problem for developers to express their intentions when they write code. It's an incredibly lazy attitude on the part of them. We have no way of knowing what the true intentions were. Perhaps they meant to have a pattern to apply to the rest of the API.

By documenting a design, the designer exposes himself to the criticisms of everyone, and he must be able to defend everything he writes. If the organizational structure is threatening in any way, nothing is going to be documented until it is completely defensible.

Quotes from The Mythical Man-Month by Frederick P. Brooks, Jr.

I've taken this quote to heart. My defense for any inaccuracies there might be is that I'm reverse engineering. I don't know what their defense is.

All this to say, it's not explained strictly by laziness. I also think there are intended patterns, but they are clarified over time. They have to balance strict pattern adherence against breaking changes, and that's not easy.

Some of this balance has been happening over time without much notice. For example, the new AppBase patterns are being translated by jussi. This effort is good because it allows the patterns to change without breaking older implementations. But it's also bad because older implementations don't have to update.

Interesting. Perhaps when memcpy from C (which today is documented very well) was new they expected it to work with overlapping memory ranges but later found that such a situation was a corner case that broke what are normally error free and optimized implementations.

This post has been included in the latest edition of The Steem News - a compilation of the key news stories on the Steem blockchain.

Hi, @inertia!

You just got a 0.97% upvote from SteemPlus!
To get higher upvotes, earn more SteemPlus Points (SPP). On your Steemit wallet, check your SPP balance and click on "How to earn SPP?" to find out all the ways to earn.
If you're not using SteemPlus yet, please check our last posts in here to see the many ways in which SteemPlus can improve your Steem experience on Steemit and Busy.

  ·  4 months ago Reveal Comment