No cookie for

A New Format for Developer Documentation

Posted by on UNCATEGORIZED

At MÄK we take developer documentation seriously. We recognize we haven’t always gotten it right, therefore we are continually trying to make it better. With new product releases starting this quarter, we will be overhauling how we present development documentation. The changes may be relatively subtle but we believe you will appreciate them.

Historically, we have always had two places developers needed to look to understand our APIs: The Developer’s Guide, which was in PDF format, and the Class Documentation, an HTML guide to class usage. These two competing formats sometimes got out of sync because they weren’t reviewed at the same time, or because the class docs were generated automatically from the code thereby instantly reflecting changes. To solve these problems, we started moving code segments from the Developers Guide to the Class Docs, but this just made the split between the two documents more troublesome.

To resolve this problem once and for all, we are doing away with the Developers Guide as a PDF and moving all the content into a single unified HTML format which is generated and highly cross-referenced every night as part of our Nightly Build Process. All of the same content will be there, but now users will be able to click through class references in the documentation to see the associated class docs. We have also started to add tutorials and other content into the web system to provide a more comprehensive understanding of our APIs.

We will likely continue to tweak some of the formatting and wording of various sections between releases this summer, so we would love to hear any cheers or jeers you may have.   Please feel free to post them as a comment here or send them to me at support@mak.com.

Finally, please know we are also considering adding the new class docs to our public web page. While we recognize a good many of our customers do not have access to the public internet as they develop, we believe we can update the documentation in real time based on feedback from those customers who do have access to it. And we will continue to provide the latest documentation in each product development package for customers to use locally.

Last modified on
Trackback URL for this blog entry.

Comments

  • No comments made yet. Be the first to submit a comment

Leave your comment

Guest
Guest 05 April 2020