Writing an API Reference guide for iOS

I’ve been asked to help develop an API Reference Guide to support the SDK for an iOS application. The initial thought is that I could use the documentation within the code to create the content of the guide. In this setup, I would be able to write the documentation within the code. This ensures that both the finished document and the code would make sense and would remain in line with each other.

The problems are that I am completely unfamiliar with iOS code. I also don’t know how best to work with the developers on this. Should I have access to the code or should I submit the documentation as simple text files? And most importantly, how do I pull the text from the code into a publishable document?

Any thoughts or ideas on this would be more than welcome.

Comments

  1. Richard S.

    The initial thought is that I could use the documentation within the code to create the content of the guide. In this setup, I would be able to write the documentation within the code.

    This is practical for API reference docs, and can be practical for example code, but is not so practical for everything you might want to document. For example, you won’t want to document API usage policies, or system architecture discussions in the code. 

    This ensures that both the finished document and the code would make sense and would remain in line with each other.

    Be careful. It’s tempting to think that just because the doc is in the code that “it will get updated” when the code does, but it’s not a guaranty. It still takes actual planned work of people to read the in-code doc and update it when code changes. It’s not a given that it’ll get updated just by proximity to the code.

    That warning aside though, it makes a lot of sense to do as much doc in code as you can. A couple of benefits of this approach are that your devs probably already know how to do doxygen markup, and you (or your build engineer) can easily automate doc-generation as part of a build process. Those are both nice. Also, if you give out your source, that’ll be the first place your customer-developers will go, so it’ll be nice for them if the code is well documented.  

    The problems are that I am completely unfamiliar with iOS code.

    Get familiar with iOS. They provide some of the best SDK documentation I’ve ever seen on the iOS developer site. It starts with very minimal assumptions about who you are and what skills you bring to the table. You can progress through simple examples and even use the device simulators for many things. It’s well worth your time. In fact, if you aren’t familiar with iOS development, it will be readily apparent to your readers in everything you write. It’s well worth your time. 

    I also don’t know how best to work with the developers on this. Should I have access to the code or should I submit the documentation as simple text files? 

    Yes, you should have access to the code your team is writing. Where it makes sense (ie API declarations), you should do your writing directly in the code. You can do this on a personal (sandbox) branch in the dev team’s repository, then merge it into the main/release branches when it reaches some modest level of maturity. 

    For documentation that doesn’t really belong in the code, you may just want to keep your source elsewhere. Text files may (or may not) be a good choice depending on many other aspects of your chosen workflow and tools. You’ll want a reasonably robust version control tool for your docs that aren’t kept in the code. 

    And most importantly, how do I pull the text from the code into a publishable document?

    There are many ways to accomplish this. Doxygen is a commonly used tool for it. JavaDoc is a similar tool, but for Java (which I assume your code isn’t). I’ve used both a fair bit, and they do what they do reasonably well, but there are some limitations in each. For example, a typical use of Doxygen is to generate HTML output. It works well, and is easy to customize with your own CSS, but if your publication workflow doesn’t play nice with HTML, it gets a little harder. Doxygen can output XML too, but you’ll need to write your own stylesheets and transforms, and there’s little documentation to help you out. 

    And of course, you can choose from among the many others out there, or even roll your own code parsing tool. There are many options. If you aren’t sure where to start, ask your dev team if they already use such a tool. If they don’t, consider Doxygen. It’s a decent tool that’s pretty easy to get started with. 

  2. Richard S.

    The initial thought is that I could use the documentation within the code to create the content of the guide. In this setup, I would be able to write the documentation within the code.

    This is practical for API reference docs, and can be practical for example code, but is not so practical for everything you might want to document. For example, you won’t want to document API usage policies, or system architecture discussions in the code. 

    This ensures that both the finished document and the code would make sense and would remain in line with each other.

    Be careful. It’s tempting to think that just because the doc is in the code that “it will get updated” when the code does, but it’s not a guaranty. It still takes actual planned work of people to read the in-code doc and update it when code changes. It’s not a given that it’ll get updated just by proximity to the code.

    That warning aside though, it makes a lot of sense to do as much doc in code as you can. A couple of benefits of this approach are that your devs probably already know how to do doxygen markup, and you (or your build engineer) can easily automate doc-generation as part of a build process. Those are both nice. Also, if you give out your source, that’ll be the first place your customer-developers will go, so it’ll be nice for them if the code is well documented.  

    The problems are that I am completely unfamiliar with iOS code.

    Get familiar with iOS. They provide some of the best SDK documentation I’ve ever seen on the iOS developer site. It starts with very minimal assumptions about who you are and what skills you bring to the table. You can progress through simple examples and even use the device simulators for many things. It’s well worth your time. In fact, if you aren’t familiar with iOS development, it will be readily apparent to your readers in everything you write. It’s well worth your time. 

    I also don’t know how best to work with the developers on this. Should I have access to the code or should I submit the documentation as simple text files? 

    Yes, you should have access to the code your team is writing. Where it makes sense (ie API declarations), you should do your writing directly in the code. You can do this on a personal (sandbox) branch in the dev team’s repository, then merge it into the main/release branches when it reaches some modest level of maturity. 

    For documentation that doesn’t really belong in the code, you may just want to keep your source elsewhere. Text files may (or may not) be a good choice depending on many other aspects of your chosen workflow and tools. You’ll want a reasonably robust version control tool for your docs that aren’t kept in the code. 

    And most importantly, how do I pull the text from the code into a publishable document?

    There are many ways to accomplish this. Doxygen is a commonly used tool for it. JavaDoc is a similar tool, but for Java (which I assume your code isn’t). I’ve used both a fair bit, and they do what they do reasonably well, but there are some limitations in each. For example, a typical use of Doxygen is to generate HTML output. It works well, and is easy to customize with your own CSS, but if your publication workflow doesn’t play nice with HTML, it gets a little harder. Doxygen can output XML too, but you’ll need to write your own stylesheets and transforms, and there’s little documentation to help you out. 

    And of course, you can choose from among the many others out there, or even roll your own code parsing tool. There are many options. If you aren’t sure where to start, ask your dev team if they already use such a tool. If they don’t, consider Doxygen. It’s a decent tool that’s pretty easy to get started with. 

Your email address will not be published. Required fields are marked *