I teach university courses on the side, and one of the courses last semester was Writing with Digital Technology, where students learned about different technologies and tools that technical writers use in the industry. Topics included HTML, CSS, XML, DITA, Markdown, GitHub, and other writing tools and technologies.
As I wrapped up last semester, my class and I looked back on the technologies we enjoyed learning. If you are getting started in technical writing, you might be interested in this list of open technologies that make technical writing easier.
HTML
Every website is built on HTML, the HyperText Markup Language. While professional technical writers might use web-based tools like Drupal or TYPO3 to create web pages, it's always nice to know how things work behind the scenes by learning HTML. While it may not happen very frequently, sometimes a web-based tool will generate incorrect HTML. Technical writers need to know how to fix web pages by editing the HTML without breaking it further.
HTML code is entirely text-based, with tags inside angle brackets. Elements are either block or inline, such as <p> to define a block paragraph or <em> to put emphasis (usually italics) on a word or phrase.
Technical writers might focus on writing content in HTML and defining styles in a separate CSS file or stylesheet to define how the content appears on the screen. This separation of content and appearance is a great way to focus on writing.
Markdown
Another way that you can write documentation is with Markdown. Markdown aims to streamline technical writing by removing as much markup syntax as possible, replacing it with standard conventions that you might use when writing in a plain text file.
For example, to start a new paragraph in Markdown, add a blank line in your text file. The next paragraph starts with the next block of text. Add headings by drawing a line under it, such as this to create a top level heading:
Title of my document
====================
And this to create a subheading in a document:
How to use the software
-----------------------Markdown is often used when writing Readme files or other project documentation on GitHub or GitLab. This makes Markdown a popular choice for open source developers as well as technical writers.
DITA
Darwin Information Typing Architecture (DITA) is essentially an XML file with a particular file structure. When creating project documentation with DITA, technical writers focus on how to reuse and remix content to create new kinds of output files.
For example, three common DITA file formats are the DITA Concept which describes a thing or a process, DITA Task which lists the steps to perform a process, and DITA Reference which provides just the facts about a topic, such as warnings or important notes.
DITA is a power tool for technical writers because you can assemble a document by creating a separate XML file called the DITAMap that compiles several DITA files about a topic. This allows technical writers to reuse content without copying and pasting between separate documents. DITA Open Toolkit and other DITA tools provide transformations that turn the DITA source into different output types including PDF documents, HTML websites, and EPUB books.
LibreOffice
If you prefer to use a traditional word processor to write documentation, LibreOffice Writer provides an outstanding open source option. Writers can leverage different styles available in LibreOffice to define chapter titles, section headings, paragraphs, and sample code within a document. LibreOffice also supports character styles that help provide emphasis or highlight source code keywords and other inline text.
The page styles in LibreOffice allow great flexibility in creating printed documentation. For example, page styles include left and right pages, typically used in longer documents to ensure that new chapters or major sections always begin on the right-hand page of a printed book. Headers and footers can be defined independently on left and right pages, providing greater flexibility in technical writing.
LibreOffice is a more traditional desktop word processor with an easy-to-learn interface. Most functionality is available directly on the toolbar, with additional features in menus. Or use the pop-out Styles pane to quickly select the paragraph, character, or page style that you want to use.
This article was co-authored by: Teagan Nguyen, Joshua Hebeisen, Aurora Dolce, David Kjeldahl, and Rose Lam.
1 Comment