Open-source News

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.

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:

And this to create a subheading in a document:

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.

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.

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.

If you are getting started in technical writing, you might be interested in this list of open technologies that make technical writing easier.

rawpixel.com. CC0.