Posts tagged documentation
I joined my current company and department a few years ago. We had some documentation for processes but most people had been around for a long time and never needed it, so it was very sparse. Sinc...
Our software documentation set (for a SQL analytics database platform) is large, because SQL and databases have many pieces. Often a single statement, function, or feature will be highly related to...
We have written a custom software framework and it has grown to the point where we are ready for documentation. This documentation will be used by other developers to share knowledge. I am concerne...
I'm writing a technical manual about creating database systems, and wondered what is the best verb tense for title names. My ideas are: Continuous (-ing) form: (e.g. "Creating a Cluster", "Creat...
In the IT industry, we often write a lot of technical documentation meant for internal use only. Those documents are often stored in an internal wiki and accessed when the need arises. The conten...
I am wondering if how we name a version of a spacecraft differs from how we name a version of a software. For software, I usually see things like "2.0.32.32" or something like that and sometimes th...
Typically, the voice of marketing content doesn't match the voice of technical content -- marketing is trying to persuade you that you need something; technical writing is generally instructing you...
Often while writing a software requirement/change-request documentation, I need to include the quoted requirements descriptively, the impacted modules, the changes provided both in UI and in logic....
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?
I currently spend a good deal of time over at Code Review and I would love to improve the quality of the reviews I write. Can you give me any insight into the structure or approach you use when wri...
I'm a self-taught programmer which means I started writing software by sitting down at an IDE and hammering out some code. When my decisions ultimately coded me into a corner I would refactor and r...
I have a highly flexible software product consisting of a series of loosely coupled microservices. Each component is effective at a single job, but may be dependent on inputs from other services. I...
I have no degree and I cannot afford to have one, however, I would really love to get into technical writing because I love writing and I am interested in web and software development. Right now, I...
I am new to programming and am entirely self-taught. I have reached a point in my writing where a solid grasp of documentation standards would be greatly beneficial. My question is not how to add d...
Say you want to talk about a piece of command-line software, like make or bash or the cp command. These commands are all lower-case, and case-sensitive (i.e. won't work on the computer if you capit...
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...
I'm writing a guide to give step-by-step instructions to complete some tasks on the computer. At some points, I need to indicate pressing keys on the keyboard; how may I format the letter/symbol to...
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 wa...
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...
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 t...
I am describing a database for a scientific publication. The database has many tables, and each table has fields (spreadsheet columns) and records (rows). I spend a lot of time discussing tables a...
Good time of the day, community! Hope, that my post won't irritate too much, but rather will be helpful for someone in future. I already made some progress myself (I mean some raw unfinished vers...
I'm having trouble finding and sticking to one word to indicate whatever value the user intends to use with my instructions. For example: Select your preferred printer. I'm wondering what s...
I'm working on a magic system that works with weaving types of power. The most commonly used power source is a magical code. I'm trying to base this code off of latex. LaTeX is a math code that is ...
For online, developer-centered documentation for a complex software product, which structure is going to be more usable: a smaller number of long, comprehensive pages, or a larger number of more gr...
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 ar...
In our documentation, we write binary numbers like this: 1010 But we write hexadecimal numbers like this: 0xABAB Now, according to the GCC compiler conventions: Numbers are normally written in...
Are they "if-else statements" or are they "if/else statements"? I'm partial to the latter, but I can see the logic of the former - both "if" and "else" are acting as a unit modifier for the noun "s...
Frequently, at least in the software world, it seems that terms get assigned a meaning over time that is more general than the original definition. REST is a good example of this. While REST refe...
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 La...
Our tech comm team has a wide variety of time-consuming, repetitive tasks they we need to automate. We are mainly using Sphinx, reStructuredText, Adobe Illustrator, and Visio. Specific things we n...
We have a tool that we cannot replace that does not support single sourcing. As a result, with instructions that involve the same node, we either repeat the same dozen steps over and over, or refer...
Quickly communicating data lineage to other stakeholders in our organization has become increasingly difficult as we scale. What are effective strategies to address this and keep it maintained? A...
I am writing the release documentation for a software product and a design flaw has been discovered after the code has been frozen. Does the documentation describing this issue change if the produc...
The deadline is looming and someone realizes the product can't be shipped without documentation. Once the product leaves the remit of the software engineers (who obviously only ever write wonderful...
I am writing the built-in help for a command line program. The exact name is irrelevant, so let's use foo as a placeholder. This utility can be called with some arguments (like foo -v) or without ...
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 ...
