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 ...
- 346
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 ...
- 355
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 ...
- 21.4k
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. ...
- 389
4
votes
Accepted
How do I start to document an API that uses C#?
Look at API documentation for C#, such as that on the Microsoft site (see here), or check out one of the multitude of repositories on Github.
Basically, API document the ways users interact with your ...
- 7,866
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 ...
- 389
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 ...
- 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 ...
- 241
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 ...
- 725
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 ...
- 1,313
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. ...
- 41
3
votes
How do I start to document an API that uses C#?
If the API you're going to document is a REST API, Tom Johnson has this excellent free online course, Documenting REST APIs.
If that doesn't fit your needs, Stack Overflow has a couple of topics that ...
- 1,895
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 ...
- 99.6k
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 ...
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 ...
- 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 ...
- 21.4k
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....
- 6,043
2
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 ...
- 21.4k
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 ...
- 753
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....
- 241
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 ...
- 3,692
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 ...
- 1,141
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 ...
- 25.5k
Only top scored, non community-wiki answers of a minimum length are eligible