search

esi / esi-issues

Issue tracking and feature requests for ESI
https://esi.evetech.net/
209 stars 23 forks source link

[META] Crowdsourced endpoint and property descriptions #471

Open CarbonAlabel opened 7 years ago

CarbonAlabel commented 7 years ago

Many of the endpoint and property descriptions in the ESI specification are nondescript, incorrect, or leave out information which might be required for someone with little understanding of EVE's game mechanics to properly utilize them.

It might be worth looking into a scheme similar to the moderately successful third-party dev docs, that would allow more experienced EVE third-party devs to enhance the existing descriptions by creating pull requests.

Robbilie commented 7 years ago

we could use githubs wiki…? :)

deadlybulb commented 7 years ago

I like the idea, I'm not sure how feasible it would be depending on what you mean. I'm assuming you'd want to crowdsource the descriptions in the swagger.json spec. It looks like some of these descriptions are auto-generated (e.g. list of alternate routes). Also, if I remember correctly, the swagger.json they end up delivering is actually assembled automatically from several independent annotated endpoints.

I can think of at least two possible ways forward:

CarbonAlabel commented 7 years ago

Also, if I remember correctly, the swagger.json they end up delivering is actually assembled automatically from several independent annotated endpoints.

That is true. For reference, here is how it is done in the only ESI endpoint which has been published so far. Moving those YAML strings from the endpoints' source code to files in a public repository would be one way of accomplishing what I'm suggesting, as well as providing a much more elegant alternative to https://github.com/xxpizzaxx/esi-archive.

If people were to start regularly creating issues here about lacking descriptions, it would be borderline spam, not to mention a pretty big waste of developer time to personally fix them all. Approving PRs made by other people (I'm guessing there would be a decent amount of people willing to make those) should be much faster, so I'd like to hear if CCP devs would consider implementing such a process to be worth their time.