I can't assume that my past work speaks for itself. I do have to put on my "sales" hat from time-to-time. I'm not that good at it because it feels yucky to toot my own horn. But here I go ...
Umm, that didn't come out right.
See discord discussion
That's no accident, bud.
API Definitions
The API Definitions are just one aspect of the devportal and this is the area that @blocktrades wants to replace with an annotation tool. According to Blocktrades, regarding my proposal:
In the past I would have voted for it for sure because the site that inertia maintained was the best source of development documentation, but after some internal discussion, a lot of our devs felt it was better to move away from the current documentation methodology, to a new one where the source code is directly annotated with the information that is then used to generate the docs.
This is great, I love documentation generated from annotations. I was aware of this from one of the meetings and it makes a lot of sense. Blocktrades continues:
We've used this method in the past in our internal projects, and I think it results in better, more comprehensive documentation (for example, it's much easier to see if some API call hasn't been documented, because it will be obvious during code reviews).
True, although I have my methods for finding missing documentation, which is part of the devportal project, so anyone can use it to see how behind the definitions are:
That last highlighted one checks the curl examples and even acts as a smoke test for the API itself.
It's not perfect, but I guarantee you, annotations are not always up-to-date either. Either way, you're going to need a tool to do comparisons and build a report on what is out-of-date (as it relates to the actual behavior). It will not always be obvious by doing a code review.
One of the things that this relies on is the jsonrpc namespace, which in theory should never be out of date. And yet:
https://gitlab.syncad.com/hive/hive/-/issues/100
This issue proves that it's possible for developers to fail to update method signatures when they should. Maybe there needs to be tighter coupling in the jsonrpc namespace. My point is, in practice, this is similar to annotations being out of date with how the method works.
Either way, someone has to maintain the annotations if the developer fails to (like hive issue 100) and be able to later detect when that happens (like the rake tasks allow right now). Blocktrades continues:
When Steemit wasn't doing this, it made sense for someone else to step up and do it like inertia was.
Steemit started doing the API Definitions before I worked there, and yes it got out of date. I expanded on it and added generators and reporting to bring it up to date. It was no accident. Blocktrades continues:
But now that we're planning to have the devs and testers directly annotating the source code, it doesn't make as much as sense to me anymore, as it seems like it will just be redundant work.
Absolutely, there will be no need to maintain both the headers and YAML database. The devportal should be altered to either import the generated documentation or (more likely) link to the generated documentation when the YAML is no longer maintained. Blocktrades continues:
Now, it doesn't have to be entirely, because inertia could come in and create tutorials, etc, that extend beyond the work done by what I plan for our devs to do. But none of that makes sense until we get going on the internal docs as a first step.
I don't see how this transition is blocking everything else. The tutorials can link to either the YAML generated documentation or the annotation generated documentation. During the transition, they might do one or the other, depending on the tutorial.
For example, pagination could point to the annotation generated documentation when it's ready. Or maybe the pagination tutorial goes away because the annotations are so good it'll be obvious how to paginate each method (unlikely).
By the way, the reason we have a dedicated tutorial on pagination is because developers do not stick to one precise pattern.
The ideal situation is that developers who know the code and all of the related complexities are also the ones who write helpful documentation on each API method.
While this is ideal, it's not typical. Often, devs write the most autistic, unhelpful comments. Not always. But often.
Likely, the developer tasked with writing the annotations will still go to devportal and copy parts of that. Which is great. I'm glad the devportal is useful for them in this transition.
Also likely, after the developer gets the annotations in, there will be additional improvements and examples that can be added later on. I guess I'll make pull requests to hived to add those examples.
My point is, I don't care if the API Definitions are stored in a header file or in YAML. It needs maintenance. If the developers are more comfortable editing headers and adding annotations, I'm flexible to also use that system.
Non-API Definitions
We can't just excise the API Definitions from the devportal and expect it all to stay comprehensive. I will still need to find a way to integrate the newly generated targets.
There's more to the devportal than just API Definitions. It has been the core purpose, I agree. When you perform a search on the devportal, most of the time, you'll find yourself reading the API Definitions. But they don't have to live in devportal.
The tutorials link to the API Definitions and the API Definitions link back to the tutorials.
Also, if you go to the devportal and search for irreversible, you get way more than methods in the result. In fact, that query only has three items that would be replaced by the annotations solution. So I would need to find a way to ensure the search functions the same or else the devportal will lose functionality. No problem. I'll figure it out.
There are tutorials, recipes (which are typically language-agnostic tutorials), resources, glossary, and much more. The approach I take to documentation is that not everyone who's on the devportal is just trying to figure out a method call. I also imagine that sometimes maybe it's an executive deciding if our blockchain is a good fit for the problems they're trying to solve.
I don't know. Maybe I need to step up my game and prove this so that the community steps up and overrides @blocktrades' decision. I'd probably need about 2,000 votes for that, though.
If you'd like to vote for my current proposal:
https://hivesigner.com/sign/update-proposal-votes?proposal_ids=[151]&approve=true
Also see: https://peakd.com/proposals/inertia