Happy Business Starts Here

Fix Developer Center documentation

I find the unusual layout of the Developer Center API Reference to be really unhelpful. Because the whole spec is on one page, it takes a really long time to load. And you can't use browser-search to navigate the specification for one API entry. 

8 Comments
Zuora Product Team
Status changed to: Unlikely

Hi @bolaurent, I'm sorry that you find it unhelpful. We specifically changed the formatting to be in line with the latest industry standard. Although the initiatl page load is a bit longer (it's actually rendering the page on the fly from metadata), once loaded, the page can easily be searched within the browser. Moving to this standard is going to help us automate the production of accurate documentation, as the documentation is actually generated from code. Please let us know if you run into any other issues, and we'll be happy to look into it.

Master

Hmm. Perhaps the resolution to my problem, then, is to download the formal specification and find a better viewing tool.

Master

It's still really bugging me. 

 

You could fix the slow loading by generating static content from the API spec, and posting the static content, only updating it when the API spec changes. This would decrease load time and server load.

Master

It takes > 30 seconds to fully load...

Master

Can you help me get a rendered version that I can save locally?

 

I tried Chrome save as webpage complete, but the save never finishes.

 
I tried https://bootprint.knappi.org/, but it needs json, and I don't see where that is offered.

 

 

Senior Tutor

@lukasz There is absolutely nothing industry standard about a 30 second load time. Due to the way it's loading, you have to keep the page in focus for it to load as well.  This isn't an isolated issue.  My whole team finds the documentation difficult to wield.

 

@bolaurent haha, yeah I also tried to download it to no avail.

Zuora Product Team

@jonconley_sg, I was referring to the formatting being industry standard, not load times. Given that we're using a JavaScript package to render the documentation on-the-fly, you'll find that certain browsers handle that better than others. Once loaded though, you should be able to navigate the documentation very quickly, in any browser. So, I'd recommend you use Chrome, which seems to have the best performance in my experience.

 

On our end, we're continuing to work on optimizing the performance. One option we're considering includes breaking up the documentation into separate pages, but that has it's own drawbacks.

Senior Tutor

@lukasz I was being unfair.  The formatting is nice and overall the documentation is quite an improvement.  You all did a nice job with that.  I look forward to the improved usability that speed improvements will bring!  I'm glad to hear that it's on the road map.