Questions tagged [api-documentation]

Application programming interfaces (APIs) are software interfaces that expose defined functionality to developers writing programs. API documentation describes these software interfaces.

Filter by
Sorted by
Tagged with
22
votes
2answers
1k views

When documenting Python, when should I use docstrings and when should I use comments?

Python programming language provides two mechanisms for documenting a function, a module or a class: Comments and Documentation strings (or Docstring). Both can be accessed by reading the source ...
14
votes
3answers
75k views

Difference b/w Abstract and Introduction writing for a research paper

I was slightly confused with differentiating Abstract and Introduction writing for a research paper. What is the difference between these sections? They seem to be similar.
10
votes
2answers
19 views

Limitations of automatic documentation

As technology advances and workflows are streamlined, some have turned to automated tools such as Doxygen, Sphinx, Swagger, etc. in order to generate technical documentation automatically. What are ...
10
votes
2answers
3k views

Good Examples of and Practices in Code Documentation

I noted in this question: What is the best way to learn technical writing? ...that a rated method to learn how to write technical documents is to imbibe good examples. Can you recommend any ...
9
votes
5answers
85 views

What are the benefits of including complete working code samples in documentation

When documenting software API so others know how to access the various methods, what data structures are used etc, I like to document each bit in detail and also include, regardless of the coding ...
8
votes
4answers
2k views

How can I write better code-based reference documentation for programming interfaces?

Programmers can write comments in code that can be automatically turned into API documentation (like Javadoc). All I have to do is add some comments explaining what a class or method does and what ...
6
votes
4answers
110 views

What is special in API documentation compared to general technical writing?

The title says it all: what is special in Application Programming Interface documentation compared to general technical writing? What aspects should I take care of?
5
votes
1answer
35 views

Are there valid reasons to write Java Annotation (or .NET XML Documentation) for private methods?

At this point, many languages have some "standard" format for writing documentation for individual methods. This includes, for example, Java Annotation and Microsoft's XML Documentation for .NET ...
4
votes
2answers
109 views

How do I start to document an API that uses C#?

I have no experience writing API documentation, but a need has arisen for it at my company. However, the only guides I can find for API Documentation are for APIs that use JSON, XML, Java, etc. What ...
4
votes
1answer
4k views

Mashery vs. Apigee

I was wondering if anyone could lend some advice as to the pros and cons between using Mashery versus Apigee for documenting an API? I have do some evaluating and have about 2 weeks to come up with a ...
3
votes
1answer
234 views

How can I publish package overviews (Java) or namespace overviews (C++) using Doxygen?

We use doxygen to generate API (reference) documentation for our code. We have a small Java API and a large C++ API. The usual tool of choice for Java APIs is Javadoc, but doxygen can do both and we ...
3
votes
2answers
464 views

API reference doc: best practices for describing opaque parameters?

The reference documentation for an application programming interface (API) is, in modern systems, usually generated from the code itself automatically. For example, for Java interfaces a typical tool ...
3
votes
1answer
38 views

Documenting a Mongo Collection Field

While writing some documentation I stumbled upon the need to describe the location of a field in a Mongo Collection on one of our corporate servers. After spending a bit of time on this I arrived at ...
2
votes
5answers
628 views

How to structure a sentence containing long code examples?

In the context of a technical manual, I need to write instructions guiding users through several standard manipulations. When providing examples of these manipulations, I have written a short sentence ...
2
votes
2answers
101 views

Tools for multiple creators/writers documentation without clouds

In many companies I've seen it that more than 1 person are writing at the same documentation (be it user manual or technical documentation) for a computer application. What I have seen in usage was ...
1
vote
2answers
73 views

What is the status of Sandcastle and are there alternatives?

Wikipedia currently lists the Development Status of the Sandcastle documentation generation software as "Stalled," citing the lack of recent releases. (There's actually contradictory information on ...
1
vote
0answers
24 views

How to avoid stacking headings in documentation, theses etc [duplicate]

I very often come into situations where I either stack headings, i.e. I have headings with no content, or where I write some content under a heading just for the sake of it not being empty. ...