---
title: "API doc survey: Do you create API doc by looking at source code?"
date: 2015-01-02
description: "API documentation survey 1.0 I need your responses to my API Documentation Survey 1.1 API..."
canonical_url: https://idratherbewriting.com/2015/01/02/api-doc-survey-do-you-create-doc-by-looking-at-source-code/index.html
---

> For AI agents: a documentation index is available at https://idratherbewriting.com/llms.txt. Markdown versions of all pages are available by appending .md to any page URL.

# API doc survey: Do you create API doc by looking at source code?

1. [1.0 I need your responses to my API Documentation Survey](https://idratherbewriting.com/2014/12/12/i-need-your-responses-to-my-api-documentation-survey/)
2. [1.1 API doc survey: The most popular type of APIs that technical writers document](https://idratherbewriting.com/2014/12/17/the-most-popular-type-of-apis-that-technical-writers-document/)
3. [1.2 API doc survey: The most common programming languages tech writers know](https://idratherbewriting.com/2014/12/22/most-common-programming-languages-tech-writers-in-my-survey-know/)
4. [1.3 API doc survey: Authoring tools preferred by API documentation writers](https://idratherbewriting.com/2014/12/24/authoring-tools-preferred-by-api-doc-writers-in-my-survey/)
5. 1.4 → API doc survey: Do you create API doc by looking at source code?
6. [1.5 API doc survey: Do you test out the API calls used in your doc yourself?](https://idratherbewriting.com/2015/01/02/api-doc-survey-do-you-test-out-the-api-calls-used-in-your-doc-yourself/)
7. [1.6 API doc survey: What IDE do you use?](https://idratherbewriting.com/2015/01/02/api-doc-survey-what-ide-do-you-use/)
8. [1.7 API doc survey result: Automating REST API documentation](https://idratherbewriting.com/2015/01/06/api-doc-survey-automating-rest-api-documentation/)
9. [1.8 API doc survey result: How do you get the source files that contain code comments?](https://idratherbewriting.com/2015/01/06/api-doc-survey-result-how-do-you-get-the-source-files-that-contain-code-comments/)
10. [1.85 API doc survey result: How to learn what you need to know?](https://idratherbewriting.com/2015/01/07/api-doc-survey-result-how-to-learn-what-you-need-to-know/)
11. [1.9 API doc survey: Most challenging aspect of API documentation](https://idratherbewriting.com/2015/01/12/api-doc-survey-most-challenging-aspect-of-api-documentation/)
12. [2.0 API doc survey: Do engineers write API doc in the source code?](https://idratherbewriting.com/2015/01/15/api-doc-survey-do-engineers-write-api-doc-in-the-source-code/)
13. [2.1 API doc survey: How much of your doc process is automated?](https://idratherbewriting.com/2015/01/15/api-doc-survey-how-much-of-your-doc-process-is-automated/)
14. [2.2 Most important factor in APIs is complete and accurate documentation](https://idratherbewriting.com/2015/01/15/most-important-factor-in-apis-is-complete-and-accurate-documentation/)

One of the questions in my [API documentation survey](https://idratherbewriting.com/2014/12/12/i-need-your-responses-to-my-api-documentation-survey/) was the following:

## **Do you create documentation by looking at the source code of API files?**

From 43 responses, the results were as follows:

![lookingatsource](https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/lookingatsource.png)

This question could have been worded a little better to provide a range of answers, such as *often, sometimes, rarely,* and *never*. A lot of people look at the source code now and then to try to clarify details about parameters or other information, but most don't use the source code intimately to get the information they need. For example, one person wrote:

> Yes, sometimes. How much has varied from job to job, and also varies for different projects - sometimes I get great information from developers, sometimes I have to investigate. I always like to get the code to check simple things like arguments, return types etc. are as advertised. In some roles I have written scripts to check such things match in code and docs. However it's not generally a good idea to work entirely from the code with nothing else to go on. You won't find the ‘why' in the code, generally.

Another person wrote:

> yes to an extent; read specs and look at code for behavior when in doubt (though code's not ready till end of dev cycle, usually, so looking at code usually ends up = last minute corrections)

And another:

> Yes, sometimes. Developer-written Javadoc does not always describe the code fully.

In contrast, some respondents are more immersed in code. One person wrote:

> I test and create the source code myself.

This is certainly a spectrum question. Many people who are perhaps developers first and technical writers second might spend all day in the source code to get the information they need, because they're also writing the code themselves. In contrast, people who are technical writers first and only interact with developers probably go into the source code only when they're hunting for missing information they can't find elsewhere.

In another survey question about main challenges tech writers face with API doc, many said getting information from developers is a major challenge. If developers don't provide the information either through meetings, specs, demos, test cases, or other interactions, technical writers probably foray into the source code to see if they can ferret out the answer.

For the most part, and especially with REST APIs, technical writers don't need to go into the source code very often. One person said,

> not needed up to now, running requests in REST and SOAP has given enough info, also looking at spec docs and other high level plan docs, as well as matching services to the actual live site.

However, from time to time technical writers do consult the source.