|
I would have the docs much more specific on the results that you'll get back. I think from the looks of it, you're using some automated doc builder which takes your internal specs for the endpoint (like the OpenAPI spec or whatever) and outputs "examples" and the other doc pages. Here is what you have now for an example response body, which is very lacking: {
"account": {
"id": "string",
"unit": "string",
"account_number": "string",
"address": "string"
},
"intervals": [
[
"string"
]
]
}
I would show something like this (clearly I don't know the exact formats or what each value is, so this is just illustrative): {
"account": {
"id": "1234567-123",
"unit": "W",
"account_number": "987654-1",
"address": "AN_ADDRESS"
},
"intervals": [
[
"(1234567.4, 123.0)"
],
[
"(1234568.4, 123.0)"
],
...
]
}
I think your docs could use a TON of manual refactoring after you output them from the automated tool OR you need to put a lot more details in the spec so that your automated tool will have better results.For instance: * What is "unit"? I assumed it's electrical units, but if that is the case, it doesn't make much sense to me, because that's not an account-level detail but rather a request detail (I should be able to add a param to the request to get Watts, Kilowatts, or whatever units I want each time). * The "address" is also sketchy, because it is just a string field, so how do I parse that? will each "line" of the address be separated by a newline, or something else? * The spec for "intervals" is a list of lists of strings, which is a weird way to output `(timestamp, value)` tuples; I would want to see that specified a bit better as well. I would expect either tuples of numbers (float, int, whatever) or something like a mapping with the meter numbers, timestamps, units, values, etc. specified like this (timestamps could be UTC seconds or (preferably) ISO strings): "intervals": {
[
"meter_id": "meter_123456",
"units": "W",
"timestamps": [
"2022-01-01T12:45:15.123456+00:00",
...
],
"values": [
1500.0,
...
]
]
{
or: "intervals": {
[
"meter_id": "meter_123456",
"units": "W",
"timestamped_values": [
["2022-01-01T12:45:15.123456+00:00", 1500.0],
...
]
]
{
Some of this is implementation details, but format and documentation matters a LOT for this stuff, if you're providing a data API as a service.That's all just from one endpoint. If you have 2 employees, I would look into hiring a technical doc writer as your 3rd if you're trying to build an "amazing developer experience" and also talking to more commercial customers who might use your product to run large data pipelines for energy controls and such. To me, the documentation is like a canary in a coal mine, and I wouldn't even attempt to use your product as-is because it would take me time to fool around with it to even see what formats the data is in and there is no differentiator from your product and others that makes me want to do that work. |