10 Software Technical Writing Interview Q&A
Software technical writing job has seen a recent boom in the last decade. This field is very well known for its handsome pay and availability of jobs.
If you are not sure what I mean just give me a search in Naukri on LinkedIn with the keywords “technical writing”
Here in this post, I have compiled some Frequently Asked Questions on Software Technical Writing and their answers.
This post is intended to help all the writers or would-be writers who want to get into Software Technical Writing.
1. What is a single-source document?
A single source document is a document that can be published into multiple outputs. For example, you do the authoring in Arbortext Editor where basically you create an XML file, and then you can publish it to multiple outputs.
Suppose you want to publish it in PDF, you can do it in HTML, in other web-based formats, or in EPUB, online help, etc. This kind of things we can do from a single XML file that is called single Sourcing and the document, in this case, is a called single source document.
A single source document is also capable of content reuse. This means that same content I can use or reference multiple places hence preventing duplication of the content.
2. What are release notes?
Release notes are the documents that contain all the release information of a particular release. I bet you have seen release notes many times.
A simple example would be your mobile release notes. When you upgrade your mobile operating system, suppose you are using MI, so when are done updating the OS you get a detailed summary page like an issue has been fixed, some buttons not working those have been fixed, some accessibility issues have been fixed, etc.
So these kinds of information of the issues which had been fixed are collectively documented and are published which forms the main contents of the release notes.
In a nutshell, release notes are the documents that contain all the release information specific to a particular release providing details of the bug fixes and enhancements done and what are the new features that are added for a particular release version.
Here is an example of the latest JIRA release notes that provide information on the enhancements and resolved issues.
3. What are your deliverables?
These are project-specific questions pertaining to your previous company or experience. So, if I am working for a software company my deliverables will include:
- Installation guide
- Configuration guide
- Get started guide
- Release notes
Or any other information in the form of a guide which you would like to provide to a user who is using your software.
4. Have you worked on FrameMaker and oxygen/What are the tools that you are familiar with?
You need to understand FrameMaker and oxygen these are tools that allow you to document and create the source document and the single source document basically the XML files.
There are many such tools that are used for authoring in the Software Technical Documentation industry. Some of them are as follows:
- Arbortext Editor
- Oxygen XML
- MadcapFlare
- XMetaL
All of these software uses DITA as a standard to generate the source XML files. You should understand that it is not possible to know all the software. The good news is that the tools are more or less the same and with a little effort they can be mastered.
Do not panic if the ask is for Oxygen and you do not know it. If you are clear of the basics of any tool, you can learn the rest faster.
For more information on the tools, see 21 trending technical writing tools
5. What is DITA?
DITA is an abbreviation for Darwin Information Typing Architecture (DITA). XML is the language in which the content/documentation is written.
DITA is an open-source standard that defines an XML architecture for designing, authoring, publishing, and managing content which is defined and maintained by the Organization for the Advancement of Structured Information Standards (OASIS).
DITA is followed as a standard for creating and managing documentation in most of the organization.
For a more detailed explanation, see the beginners guide to DITA.
5. What is DDLC?
DDLC is an abbreviation that stands for Document Development Life Cycle. DDLC is a corresponding and concurrent process that is followed along with Software Development Life Cycle (SDLC).
You need to understand that DDLC and SDLC run in parallel and go hand-in-hand.
Software development life cycle will be the life cycle for the developers, testers, business analysts, project managers, basically, the Dev team guys who take care of the development and coding part, and in parallel, you will take care of the DDLC process to create your document for DDLC.
It consists of stages as follows:
- Understanding and gathering the requirement.
- Designing your document (forming a high-level TOC).
- Developing the document (creating those XML source files)
- Get the doc reviewed (by the Project Manager or an SME)
- Publishing the contents (in HTML, PDF, etc).
6. How do you approach an SME?
Subject Matter Experts (SMEs) can be your Business Analyst or Developers or Project Managers depending on the fact that they possess all the information on the product. So you want to approach them to get all the information required to get the documentation done.
Mostly in my case Business Analyst and the Project Manager is my SME. So, I would first go through the work/task which is assigned to me to get all the details for the documentation and analyze it on my own. If it is clear then all ok then no need to approach the SME itself and if it is not clear and more inputs are required then for information gathering you need to speak with the SME.
So mostly I'll schedule a meeting if more pieces of information are required and more aspects need to be discussed. Sometimes only small information or confirmations are required. For those instances, I'll just ask the SMEs over slack/teams (any messenger).
7. What do you mean by topic-based authoring?
Topic-based authoring is the process of breaking down the content of a user guide or complete documentation into different meaningful individual topics.
Basically, you create all the different individual topics for each of the purposes and then assemble them in a meaningful hierarchy.
For example, you create the following types of the topic to create a handbook:
- Task topic: Contains procedural steps or “How to” information.
- Concept topic: Contains descriptive info or “What is” information.
- Reference topic: Contains all information in the form of tables.
For a more detailed explanation, see the beginners guide to DITA.
8. How do you start writing a document or any topic?
Basically, the interviewer here is looking at you to answer “how do you approach or how do you start looking into things when work is provided to you.”
You must answer, I will see what informations are available for the works assigned to me. I will go through the work management tools (such as JIRA) or any other tool through which work is assigned.
If I get all the required information then all good or else, I will reach out to an SME for more inputs. Once all the inputs are available, I will do the hands-on of the new feature/enhancement in the test environment of the product (Generally a writer is provided with all access to test environments so that they can play with the UI to understand it better).
When you are able to do hands-on it means one or more of the following:
- I am able to navigate through the UI and see what changes are done (sometimes you get a “before” and “after” image)
- I am able to verify all the acceptance criteria of the developer task
At this point in time, you should get the idea that which document should be impacted. For procedural steps to perform an action, you should impact the user guide, handbook. For any enhancements done, you should impact the release notes.
This is how you start and finish documenting a new feature or enhancement.
For example, consider a new field is added in the UI. So you would look for the new and old field names, any before and after images attached by the dev team.
When you get all these inputs you can login to the test environment and navigate to the required location and verify the new field is showing up.
You are now all set for authoring. Do the changes in the Release notes and push them for the review process.
9. What is structured, unstructured authoring?
Unstructured authoring is the practice of documenting the information in a more flexible and suitable layout that does not have to abide by any standards like DITA.
For example: Authoring in Microsoft Word. You can define a template in the .dotm files and follow the same format or layout as per your choice across all the documentation.
Structured authoring on the other hand has a specified format and abide by the standards such as DITA. Generally, markup language like SGML, XML is used for structured authoring which has a specified format of tags placement. You can not enter random content everywhere. Structured authing is done in Oxygen, Arbortext, and other tools supporting DITA standards.
10. What style guide you use in documentation?
The style guide to follow varies as per the organization. If you are in the aerospace domain, you generally follow Simplified Technical English.
On the other hand, in the Software domain, MSTP is considered the bible when it comes to style guides.
Most organization have developed their in-house style guide that is derived from the MSTP.
11. What are the User guide and Installation guide?
A user guide gives the user information that allows you to configure things or provide you information with some setup that you can perform to customize as per your requirement. You can customize your software by following the procedure that Is present in the user guide. Also, a user guide gives you the basic walkthrough of each and every component of the user interface of your software. So those kinds of information you can find in your User guide.
The installation guide will contain all the information that you need to perform step by step in a sequential manner starting from unzipping the file then what you need to install, what you need to run, what you need to rename etc in order to install the software.
Please note the installation guide is for the on-premise costumes only, if the software is in the cloud then there will be no requirement of the installation guide for the customers.
0 Comments