I train college programs on the aspect, and one of many programs final semester was Writing with Digital Technology, the place college students discovered about totally different applied sciences and instruments that technical writers use within the business. Topics included HTML, CSS, XML, DITA, Markdown, GitHub, and different writing instruments and applied sciences.
As I wrapped up final semester, my class and I seemed again on the applied sciences we loved studying. If you’re getting began in technical writing, you may be on this listing of open applied sciences that make technical writing simpler.
HTML
Every web site is constructed on HTML, the HyperText Markup Language. While skilled technical writers would possibly use web-based instruments like Drupal or TYPO3 to create internet pages, it is at all times good to know the way issues work behind the scenes by studying HTML. While it could not occur very ceaselessly, typically a web-based software will generate incorrect HTML. Technical writers have to know how one can repair internet pages by enhancing the HTML with out breaking it additional.
HTML code is fully text-based, with tags inside angle brackets. Elements are both block or inline, comparable to <p> to outline a block paragraph or <em> to place emphasis (often italics) on a phrase or phrase.
Technical writers would possibly give attention to writing content material in HTML and defining types in a separate CSS file or stylesheet to outline how the content material seems on the display. This separation of content material and look is a good way to give attention to writing.
Markdown
Another means you could write documentation is with Markdown. Markdown goals to streamline technical writing by eradicating as a lot markup syntax as attainable, changing it with commonplace conventions that you simply would possibly use when writing in a plain textual content file.
For instance, to start out a brand new paragraph in Markdown, add a clean line in your textual content file. The subsequent paragraph begins with the following block of textual content. Add headings by drawing a line underneath it, comparable to this to create a prime degree heading:
Title of my doc
====================
And this to create a subheading in a doc:
How to make use of the software program
-----------------------
Markdown is commonly used when writing Readme information or different undertaking documentation on GitHub or GitLab. This makes Markdown a preferred selection for open supply builders in addition to technical writers.
DITA
Darwin Information Typing Architecture (DITA) is basically an XML file with a specific file construction. When creating undertaking documentation with DITA, technical writers give attention to how one can reuse and remix content material to create new sorts of output information.
For instance, three widespread DITA file codecs are the DITA Concept which describes a factor or a course of, DITA Task which lists the steps to carry out a course of, and DITA Reference which supplies simply the info a couple of subject, comparable to warnings or vital notes.
DITA is an influence software for technical writers as a result of you possibly can assemble a doc by making a separate XML file referred to as the DITAMap that compiles a number of DITA information a couple of subject. This permits technical writers to reuse content material with out copying and pasting between separate paperwork. DITA Open Toolkit and different DITA instruments present transformations that flip the DITA supply into totally different output varieties together with PDF paperwork, HTML web sites, and EPUB books.
LibreOffice
If you favor to make use of a conventional phrase processor to write down documentation, LibreOffice Writer supplies an excellent open supply possibility. Writers can leverage totally different types out there in LibreOffice to outline chapter titles, part headings, paragraphs, and pattern code inside a doc. LibreOffice additionally helps character types that assist present emphasis or spotlight supply code key phrases and different inline textual content.
The web page types in LibreOffice enable nice flexibility in creating printed documentation. For instance, web page types embody left and proper pages, usually utilized in longer paperwork to make sure that new chapters or main sections at all times start on the right-hand web page of a printed guide. Headers and footers could be outlined independently on left and proper pages, offering larger flexibility in technical writing.
LibreOffice is a extra conventional desktop phrase processor with an easy-to-learn interface. Most performance is offered straight on the toolbar, with further options in menus. Or use the pop-out Styles pane to shortly choose the paragraph, character, or web page fashion that you simply need to use.
This article was co-authored by: Teagan Nguyen, Joshua Hebeisen, Aurora Dolce, David Kjeldahl, and Rose Lam.
