Writing Stack Exchange
Writing Stack Exchange

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.

API documentation is a type of .

API documentation sometimes includes .

20 questions
24
votes
2 answers

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 code, but the latter is also available by calling…
DYZ
  • 383
  • 2
  • 10
14
votes
3 answers

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.
Ravva Gaurav
  • 143
  • 1
  • 1
  • 4
10
votes
5 answers

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 language, a "hello world" style sample API client…
Lefty G Balogh
  • 554
  • 5
  • 8
10
votes
2 answers

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 the most glaring limitations to these tools, and…
Timtech
  • 351
  • 1
  • 5
10
votes
2 answers

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 examples of good code/ database documentation that have…
Stefan Piskorski
  • 115
  • 1
  • 6
8
votes
4 answers

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 arguments it takes, and software turns those…
Monica Cellio
  • 21,489
  • 3
  • 68
  • 110
6
votes
4 answers

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?
Gergely
  • 161
  • 2
5
votes
1 answer

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 Languages. These formats are generally highly…
EJoshuaS - Stand with Ukraine
  • 415
  • 3
  • 9
4
votes
1 answer

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 proposal as to which to use. I've used Mashery…
Sanjay Srikonda
  • 41
  • 1
  • 2
4
votes
1 answer

What to do when API objects and UI names are different?

This question is in reference to API documentation. Say the name of an object is "Action" in the backend, but "Step" in the UI. We cannot rename objects. My approach is to explain that Action = Step in the UI, and to use the term "Action" so that…
801Jacq
  • 41
  • 2
4
votes
2 answers

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 is the best way to dive into API documentation…
Calley
  • 43
  • 2
3
votes
2 answers

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 is Javadoc. One property of such generated…
Monica Cellio
  • 21,489
  • 3
  • 68
  • 110
3
votes
1 answer

What are the conventions for formatting links to two API references in software user guide text?

Background I'm working as a technical writer on a software project where there are three related documents: a user guide, a Python API reference and a C++ API reference. The user guide describes how to use the classes, methods, and so on and then…
JaynieP
  • 33
  • 3
3
votes
1 answer

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 have decided to use a single tool for both. With…
Monica Cellio
  • 21,489
  • 3
  • 68
  • 110
3
votes
1 answer

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 the…
Shanimal
  • 131
  • 3
1
2