[drewkim]

Thanks for the feedback; as an early stage startup with two employees, we'll often miss things here and there, so I appreciate the callout for how we can improve our docs. While we may not be established right now and have some work to do, I'm confident we can build an amazing developer experience given time. UtilityAPI might have very detailed docs, but we think the end to end usability is still lacking. This has been the consistent theme we've heard from developers that we've interviewed.

I'm not sure I agree with UtilityAPI being founded by "tech people", though we may have differing definitions on what that means. It seems like most of the high level execs come from the energy industry and don't have software engineering experience.

Could you give examples of the specific details we could add to the website to make it easier for you to onboard?

[ziggus]

The founders may have energy industry experience - which is what you want, since it's the operating domain and they'll have industry information and contacts that 'outsiders' won't - but they seem to have a pretty strong development team: https://utilityapi.com/team.

[qqqwerty]

The founder is pretty active on hn[1]. And coincidentally, his most recent comment is about why it makes sense to work at an energy company as part of market research.

[1] https://news.ycombinator.com/threads?id=diafygi

[ok_dad]

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.

[drewkim]

Thanks for the great advice! We've created more detailed responses, so hopefully there's now a clearer picture of the output for each endpoint. We've added the more implementation-heavy recommendations (like changing the request body for interval data and splitting the address schema into multiple fields) to our roadmap to be implemented shortly. Really appreciate the scrutiny; way better to work everything out now than having developers run into usability issues. Please let us know if there's anything else you notice!