21 votes
Accepted

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

PEP 8 -- Style Guide for Python Code categories comments and document strings (a.k.a. docstrings) under comments sections. Comments Block Comments Inline Comments Documentation Strings Block ...
Raghav Dinesh's user avatar
9 votes

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

Code comments and docstrings have different purposes and audiences: Developers write docstrings to describe the function's behaviour. Other developers, who use this function, read docstrings to find ...
Nick Volynkin's user avatar
7 votes

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

API stands for "application programming interface". API documentation is addressed to programmers who will use that interface to accomplish some task. While all technical writing is addressed to ...
Monica Cellio's user avatar
5 votes

Limitations of automatic documentation

Automated systems such as Sandcastle and Swagger are good at converting code syntax into documentation. Those will produce marginal documentation. What they don't do is add insight into the calls. ...
ForEachLoop's user avatar
4 votes

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

Working samples is an absolute must for all APIs. Period. Reference pages especially need one. Not including them overlooks the fact that API documentation is used by a range of people. It's short ...
ForEachLoop's user avatar
4 votes

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

I can understand the reasoning from both sides. A complete quick start is essential to ensure that the reader has sufficient information to see the product running correctly, and is able to ...
Jason Fox's user avatar
  • 477
4 votes

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

The value of adding code examples to documentation depends on the example itself as well as the API or library in question. I work with a widely used software library, and we have a stated expectation ...
wowsuchnamaste's user avatar
4 votes
Accepted

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

I think it really boils down to the fact that there are two different audiences/purposes for the documentation. Documenting private methods probably isn't super important when it comes to generating ...
thesquaregroot's user avatar
4 votes

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

This happens all the time. Sometimes it's not even the programmers' fault. :-) I agree that you must use the API names. After all, you are documenting what needs to be used in programming. Yes, you ...
user8356's user avatar
  • 1,333
3 votes

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

First of all, let’s make it clear, what API means. API stands for Application Programming Interface. API is a set of tools, communication protocols, and subroutine definitions for building software. ...
Kesi Parker's user avatar
3 votes

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

I would say an API needs reasonable examples of use, and needs attention paid (or links provided) to other closely related elements of the API; even if it is just like "See xyyGraphInit". You want ...
Amadeus's user avatar
  • 101k
3 votes

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

There are different types of examples and they serve different purposes. One type is the quick-start example that this answer describes: a complete, but small, runnable example packaged in a form ...
Monica Cellio's user avatar
3 votes

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

Abstract An abstract can be defined as a summary of the information in a document. It should not exceed 250 words It should be written in one paragraph. It should be written in the past tense as it ...
rahmuddin azizi's user avatar
3 votes

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

The writing of the abstract and introduction of a paper is a very difficult task because if you have 1000 readers most of them read these parts and your paper evaluation strongly depends on these ...
Hadi's user avatar
  • 131
3 votes
Accepted

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

We solved this by adding overview files in Markdown format into the source tree and making one small configuration change. In Doxyfile, we set GENERATE_TREEVIEW to yes. This enables the sidebar ...
Monica Cellio's user avatar
2 votes

Documenting a Mongo Collection Field

How do you document X? It depends on who's going to read the document. As a rule of thumb I use to look at my documentation from two perspectives; the system perspective and the audience perspective....
Erk's user avatar
  • 6,100
2 votes
Accepted

What is the status of Sandcastle and are there alternatives?

Eric Woodruff took over Sandcastle in 2012. Due to reservations Microsoft's legal department had related to transferring the project itself, Woodruff forked the project as Sandcastle Help File Builder....
wowsuchnamaste's user avatar
2 votes

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

The purpose of API documentation is to explain how to use the API. Providing sample code of how to use key features is a good way to demonstrate the intended usage. A good example of this is the ZMQ ...
sphennings's user avatar
2 votes

Does a technical writer need API experience for writing API documentation?

I spent decades writing books about things I didn't have experience with when I started each book, because they didn't really exist before I wrote the book, which was released at the same time as the ...
Kate Gregory's user avatar
  • 3,760
1 vote
Accepted

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

So a common technique I have found is for online or digital documentation, to offer the information for the different languages as a selectable dropdown or tabbed panel in some way. Either as a tabbed ...
Joelle Boulet's user avatar
1 vote

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

In one sense you could say, Nothing. All technical writing should be clear, give good examples, etc. The main thing that comes to my mind is that for an API, you pretty much have to have the bulk of ...
Jay's user avatar
  • 25.6k

Only top scored, non community-wiki answers of a minimum length are eligible