There is no single tool for documenting articles, books, or any article in this digital era. The preference is based on the type of content and how must assistance you require from the leading vendor products. No single authoring application fits all your requirements. In this article, we will discuss in detail about types of editor, their benefits, and editor -writers relationship.

For instance, if you wish to create a large document, the technical writers prefer Adobe FrameMaker, because, they can use the schema definition file (SDF), to create and validate the structured content, before arranging the chapters in a logical order for publishing the FrameMaker output.

Microsoft Word has the ability to handle the document in a document object model (DOM), which enables it to handle large documents.  I have mentioned the capability of each application further in this document.

Either of the applications mentioned above requires deep learning and understanding the insight of the product.

Nowadays, organizations use industry-leading software, such as “Arbortext editor”, or “Oxygen XML Editor” to work on structured content, and allows the documentation teams to collaborate on large or complex documentation projects., to generate maintenance manuals, service guides, and eLearning materials as well as other marketing, sales and reference documents. Arbortext editor word processing interface makes it easy for authors to create and edit XML content for reuse and automated publishing. DITA, S1000D.

Organizations use “Arbortext editor”, or “Oxygen XML Editor” as a front-end tool, with content management system as the backend, for example, Astoria, WordPress, Joomla, Drupal, and so on. In addition, if a certain portion of the content in a single document, needs to be reused across multiple deliverables, the Arbortext editor provides content reference, facilitating only the copy of the source content shared to relative destination.

LaTeX is widely used in academia for the communication and publication of scientific documents including mathematics, statistics, computer science, engineering, physics, and so on. It does not require any Math equation editor. The equation and mathematical expressions can be written in the plain text following the standards described by LaTeX, and the equations are properly rendered while generating the output. The equation can include several superscript or subscript, it is a breeze to document in LaTeX.

Most of the scientific community, involved in Research institutions, often prefer LaTeX, so that the document could be created without depending on any other commercial product available in the market. Projects such as Digital signal processing (DSP), Molecular Graphics, Image Processing, Neural network algorithms relay all LaTeX without any dependency.

Markdown is a lightweight markup language (LML). Markdown is a text-to-HTML conversion tool for web writers easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML

Document360 application also supports Markdown syntax. For more information about how to use Dcoument360 to create Markdown content and view the same content in an HTML view simultaneously, refer to the section titled “Create Markdown using Document360 Integrated Markdown Editor” in this document, or watch the demonstration on the YouTube

An intuitive knowledge base software to easily add your content and integrate it with any application. Give Document360 a try!

Get Started

 

List of Tool used for documentation

Also Read: How To Create A User Manual

The perception that Tools can be learned, but how to understand technology in the product

Everyone in the IT industry says, the tools can be learned, unknowing of the fact what is within this great product, that serves document creation for technical writers and business needs. The best of the functionality, technology, CORBA, SOAP, REST, Server Push, Client, refreshable web query, Pivot Table, the Component Object Model (COM), all existed since then. It only evolved. The help authoring tool also served as Software +Service architecture, before it became a Software as a Service model.

I observe that many features developed before the internet, such as Form letters and many enhanced features were not utilized or realized to the potential purpose for which they were intended.

People abruptly judge and conclude on any product (Be it Microsoft, Adobe, Madcap Flare) without taking time to go deep into the insight and technology being implemented on a specific product. They quickly conclude that Microsoft Word within the Microsoft Office suite does not support long documents. It is the designers and architecture perceptive to how to conceive a product taking the community at large. I wonder how many people really understood the Open document format?

Analogy: Wright brothers discovered airplanes, this evolved as Boeing and Airbus, Archimedes principle of buoyancy helped build huge ships and aircraft carriers, James watt invention led to a steam engine. Therefore, any technology that is seen by the new generation should remember that the technology evolved well before the internet and they are converging with multiple technologies. True.

Adobe FrameMaker

Adobe FrameMaker is a documentation tool designed for writing and editing large or complex documents. The output of a file could be an unstructured or structured document. How does it create a complex documents? If you have observed all applications of Adobe, mostly each application, combines a set of files, or layers and the generated as a single output file. For example, to create a single FrameMaker document, you arrange all the chapters of the document as a list in FrameMaker and then generate those chapters into a single document. Similarly, all Photoshop images are layered inside the Photoshop file, and the resultant output file is a flattened file leveraging all layers into a single file.

In a real scenario, FrameMaker uses Element Definition Document (EDD), where rules are predefined to check the validity of the document while working on the structure of the document. EDD is similar to Schema Definition File (SDF), Document Type Definition (DTD) and so on. A widely used representation for structured documents is HTML, a schema defined and described by the W3C. However, HTML includes meaning-oriented components such as paragraph, title, and code; but also, format-oriented ones such as italic, bold, and most table.

XSD (XML Schema Definition), a recommendation of the World Wide Web Consortium (W3C), specifies how to formally describe the elements in an Extensible Markup Language (XML) document. 

Structured FrameMaker: Structured documents generally focus on labeling things for processing purposes, rather than just formatting. enabling efficient integration with databases, search systems, online catalogs, and so on.

Unstructured FrameMaker uses tagged paragraphs without compelling any logical structure.

The Structured FrameMaker authoring interface provides the following tools to enable authoring in structured (hierarchical) documents:

Structured View

Displays the hierarchical structure of the document as shown above. You can add, remove and move elements in this pod as you author your structured document.

Elements Catalog

Displays the list of elements available for use in the current document. The elements in the list are defined in the structured application on which the current document is based. By default, the elements that display in the list are based on the insertion point in the document. This ensures that you do not inadvertently place elements at invalid locations in the structured hierarchy. For more details, see Working with elements.

Attributes pod
Displays the list of attributes for the currently selected element. Set or remove values for the attributes of an element. For details, see Working with attributes.

Views

This topic explains the three editing views in FrameMaker: XML View, Author View and WYSIWYG View.

FrameMaker has three views that help you author your content:

• XML View allows you to work with the plain XML code of your structured FrameMaker XML files.
• Author View simplifies structured authoring by keeping out unstructured FrameMaker features and features not relevant for XML authors, such as page numbers. If you have enabled a Simplified XML view, you get a form-like view of your document.
• WYSIWYG View is a classic FrameMaker, unstructured and structured. This view displays page breaks, headers and footers, all keyboard shortcuts, and all menus.

Why Microsoft Office Suite

Working with Microsoft Office is fun. Why? Because, it is the first Microsoft Office application, which comprises Microsoft Word, Microsoft Excel, PowerPoint, and Microsoft Access. And this combination brought down the size of each application. Otherwise, each application would have its own individual spellchecker – Dictionary and Auxiliary dictionary and would be too large. You invoke the spell checker service and the application check for the spelling errors in the whole document.

Adding different Page Layout in a single document

Microsoft Word supports different page orientations, such as Portrait and landscape. You can add different orientations using the section breaks. Use page breaks and section breaks, appropriately to suit the documentation requirement.  In addition, the Fields commands enable the automation process within the document.

Adding multilevel list for Table of Contents and Sub-topics

The advantage of a multilevel list is that you can define a multilevel list for a Table of Content to display all the corresponding styles in a hierarchical structure with the nested subtopics.  This hierarchical display quickly defines the number of subtopics associated with each main topic.

Microsoft Style Guide

To maintain consistency in language, tone, clarity, consistency, and conciseness across all the deliverables, it is recommended that the author first refers to either Microsoft Manual of style or style guide standards developed in-house or in the organization among the team members.

Understand Fonts

Microsoft Word supports several types of fonts, and behavior: • Raster • Vector • Printer • Postscript • Dynamic and scalable fonts. Microsoft can generate intermediate fonts automatically when you type a custom font size in the Size text box.  

For example, if have point 14 and 16 in the font list, and you enter point 15, you will not know whether the font 15 was generated from point 14 or point 16.

How to create interactive Form letters using Form commands?

You can create a simple documents or complex documents. But if for instance, you create a form letter or Mail merge document, you will create one input file with N number of records, delimited with comma or TAB, then associate this file to the master document. Eventually, you will generate a merged document using these two documents. You can incorporate conditional fields, in the master document. You will then realize how much memory, storage space and power is required to complete the task. Today, I am not certain how many of them are trying this feature.

Understanding Cascading style sheet (CSS)

CSS is not new. This concept existed since the desktop version of Microsoft word. CSS can be created for a document or an already created style sheet in another document can be included in the current document, this referred to as external stylesheet in CSS terminology. Now you can create a structured document based on this style sheet. This means CSS knowledge is built into the product.

Using Cross-references

This is a very old concept where other vendors do incorporate in their publishing tools these days. Cross-reference enables you to create a link or a bookmark within the document. So, when you click on a particular link, you navigate to an exact location within and outside the document.

Understanding Plug-ins, Dynamic Link Library (DLL) and APIs

Microsoft provided these techniques long back to help extend the functionality of the existing application either through third-party APIs or by creating libraries.

Converting from Binary to XML Format

Earlier versions of Microsoft Office saved file(s) in their respective binary format – doc, xls, ppt and so on). This format is replaced by an open document format known as XML.  Now, Office XML format can be utilized by other applications.

Another advantage is that Microsoft office documents will not corrupt because the technology it leverages is a document object model (DOM).

For example, a Microsoft word document created prior to saving as XML cannot be recovered if corrupted, the document has to be recreated all again, because the documents were in binary format. So today if the document gets corrupted, only that portion of content needs to be looked at in order to fix the issue. The Word document will still open.

Microsoft Office supports XML format to Microsoft Excel, such XML Schema, XML Map, and XLST –FO. Therefore, go deep into an understanding of leading vendor products to gain knowledge.

Microsoft introduced drag-and-drop

Microsoft was the first to introduce Drag-and-Drop to move an object from a source location to a destination application (Workspace, Canvass) without copying the data to the clipboard.

For example, if you have copied some data to the clipboard, then paste option in the menu automatically gets highlighted. But, when you drag-and-drop some data within the Word document, the clipboard data retains the copied data and not the drag-and-drop data. 

Inline graphics and Embedded graphic

When you include Mathematical equation, using the mathematical editor in the document, the images need to be inserted as an in-line graphics, so that when adding or deleting content the inline equation moves along accordingly. Embedded graphics are just placed in the document.

Microsoft Paste Special (OLE 1.0, OLE 2.0 and COM)

This technology is very pleasing and amazing. Many of them regularly use Paste special command. The Paste Special command in Microsoft Office is also referred to as OLE in Microsoft Office, Microsoft ActiveX, and Applet in JAVA. All the terms are the same. They work as a client-server architecture. But, in software development, few components executing at the design time itself, while creating an ActiveX component, even before the full component is developed. For example, the TIMER control.

What OLE 1.0 and OLE 2,0 works?

OLE 1.0 is an “Out-process” communication and OLE 2.0 is an “In-process” communication.

How OLE 1.0 works?

After placing an image from photoshop within the Microsoft Word using paste special command, when you double-click on the image, an OLE 1.0 object placed within the document, opens a new process, which you can view in the windows task bar.

How OLE 2.0 works?

After placing an image from photoshop within the Microsoft Word using paste special command, when you double-click on the image, an OLE 2.0 object placed within the document, opens the image with Photoshop application at the same location within the Microsoft Word document. The menu of Microsoft Word changes to Photoshop, when you exit Photoshop, you return to Microsoft Word. No new process is shown in the windows taskbar.

Understanding Stub, Proxy and Marshalling using Microsoft Office

OLE is a Client and Server model. You could also consider as a container.

In OLE, communication between two applications is known as marshaling. The client is called Stub and the server component is Proxy. The technology that performs communication between stub and proxy is through the Component Object Model (COM). Similarly. So across distributed COM environment is referred as Distributed COM (DCOM).

This concept is well understood by the software developers, but the documentation team, documentation managers never brought the analogy to the authors using Microsoft Office. Maybe, they were not aware or knew whether the term exists.

ActiveX Control in Web

In the previous section, I have described OLE, which is a Client and Server model. Now, let see how ActiveX control works. ActiveX control is a useful technology that helps view Microsoft Word document in the Web browser. The ActiveX Web control contains a Microsoft Word preview viewer, which quickly opens the document to have a preview.

Refreshable Web Query

Even before the Cricket web site was developed, Microsoft brought Client-Pull technology and Server Push technology. Such feature is incorporated in Microsoft as Refreshable XML query and in Microsoft Active Desktop way back.

You can configure the delay time for the server to push or may decide against specifying the delay.

Conditional Formatting

The conditional formatting was first conceived by Microsoft in Microsoft Excel. Using Microsoft Excel conditional formatting, you can instantly identify and understand the results relevant to the context, assigning a variety of colors to the result, depending on certain conditions assigned to the cell.

As I mentioned earlier, the implementation of conditional formatting may differ. Today conditional formatting is used to generate various output (PDF, Web, Mobile) from a single document 

Run PowerPoint within Microsoft Word

Run “PowerPoint Presentation” from within a Microsoft word document, by selecting only required slides from the source PowerPoint presentation. For example, only six PowerPoint slides will be executed, when you double-click on the object in a Microsoft Word document.

Arbortext Editor 

Arbortext Editor is the industry-leading software used globally for working with structured content. It enables your authoring teams to collaborate on large or complex documentation projects that need to be disseminated in multiple forms.

Arbortext Editor documents can be transferred to any SGML or XML-compliant system.

Oxygen XML Editor

The Oxygen XML Editor is a multi-platform XML editor, XSLT/XQuery Debugger and Profiler with Unicode support. Oxygen XML Editor is a Java-based application, so the application can execute on Windows, Mac OS X, and Linux. It also has a version that can run as an Eclipse plugin.

What is AsciiDoc?

AsciiDoc belongs to the Markdown family – a lightweight markup language. AsciiDoc supports all the structural elements necessary for drafting articles, technical manuals, books, presentations and prose.

AsciiDoc files are designed to be viewed, edited and printed directly or translated to other presentation formats. AsciiDoc is associated to one aspect, in particular, that is writing., does not require angular brackets, and integrates with semantics.

AsciiDoc comprises of two things:

1. A plain-text writing format for authoring notes, articles, documentation, books, eBooks, web pages, slide decks, blog posts, man pages (Unix) and more.
2. A text processor and toolchain for translating AsciiDoc documents into various formats, including HTML5, DocBook, PDF and ePub.

Who’s using AsciiDoc?

AsciiDoc is a lightweight markup language, it has not been extensively adopted by many organizations, but few of the organization listed below, have adapted to AsciiDoc

1. O’Reilly and MakerPress
   • Clojure Cookbook (AsciiDoc source)
2. GitHub supports AsciiDoc syntax in repositories, wikis and lists (powered by Asciidoctor)
3. Context and Dependency Injection for the Java EE Platform (CDI)
   • Specification (AsciiDoc source)
   • Website (AsciiDoc source)
4. Git user manual (AsciiDoc source)
5. Enterprise Web Development: From Desktop to Mobile (AsciiDoc source)

These examples are more than just testimonials. They should give ideas about how to be successful with AsciiDoc for your own project.

Docbook

DocBook is a semantic markup language used to author technical documentation, such as hardware and software. DocBook allows the creation of document content in a logical structure for presentation-of-neutral content. The content can then be published in a variety of formats, including HTML, XHTML, EPUB, PDF, man pages, Web help[2] and HTML Help, without requiring users to make any changes to the source.

DocBook provides a vast number of semantic element tags. They are divided into three broad categories: structural, block-level, and inline.

• Structural tags: Specifies broad characteristics of their contents. The book element, for example, specifies that its child elements represent the parts of a book. This includes a title, chapters, glossaries, appendices, and so on. DocBook’s structural tags include, but are not limited to:
• set: Titled collection of one or more books or articles, can be nested with other sets
• book: Titled collection of chapters, articles, and/or parts, with optional glossaries, appendices, etc.
• part: Titled collection of one or more chapters—can be nested with other parts, and may have special introductory text
• article: Titled, unnumbered collection of block-level elements
• chapter: Titled, numbered collection of block-level elements—chapters don’t require explicit numbers, a chapter number is the number of previous chapter elements in the XML document plus 1
• appendix: Contains text that represents an appendix
• dedication: Text represents the dedication of the contained structural element
• Structural elements: Includes other structural elements. Structural elements are the only permitted top-level elements in a DocBook document.
• Block-level tags: Comprises elements like paragraphs, lists, etc. Not all these elements can directly contain text. Sequential block-level elements render one “after” another. After, in this case, can differ depending on the language. In most Western languages, “after” means below: text paragraphs are printed down the page. Other languages’ writing systems can have different directionality; for example, in Japanese, paragraphs are often printed in downward columns, with the columns running from right to left, so “after” in that case would be to the left. DocBook semantics are entirely neutral to these kinds of language-based concepts.
• Inline-level tags: Includes elements like emphasis, hyperlinks, etc. They wrap text within a block-level element. These elements do not cause the text to break when rendered in a paragraph format, but typically they cause the document processor to apply some kind of distinct typographical treatment to the enclosed text, by changing the font, size, or similar attributes. (

Sample document

Note : Semantically, this document is a “book”, with a “title”, that contains two “chapters” each with their own “titles”. Those “chapters” contain “paragraphs” that have text in them. The markup is fairly readable in English.

Schemas and validation

Rules are formally defined in the DocBook XML schema. Appropriate programming tools can validate an XML document (DocBook or otherwise), against its corresponding schema, to determine if (and where) the document fails to conform to that schema. XML editing tools can also use schema information to avoid creating non-conforming documents in the first place.

Because DocBook conforms to a well-defined XML schema, documents can be validated and processed using any tool or programming language that includes XML support.

What is Asciidoc and Asciidoctor?

AsciiDoc is a text document format for writing notes, documentation, articles, books, ebooks, slideshows, web pages, man pages, and blogs. AsciiDoc files can be translated through the Asciidoctor toolchain to publish other formats including HTML, PDF, EPUB, DocBook and man page.

Any text editor can be used. Some websites, like GitHub, render AsciiDoc files directly into HTML.

The following listing is an example of a simple Asciidoc file.

LaTeX

LaTeX is widely used in academia for the communication and publication of scientific documents in many fields, including mathematics, statistics, computer science, engineering, physics, economics, linguistics, quantitative psychology, philosophy, and political science.

LaTeX is used in the software industry for writing knowledge base articles, and for creating manuscripts in which the document consists of substantial mathematical formulas and mathematical expressions. Any research organization, involved in high-performance computing solution, use LaTeX for document preparation. For example, Projects involving digital signal processing (DSP), weather forecasting, Fine element modeling (FEM), Image processing, Neural networks, seismic, and so on.

LaTeX is a software system for document preparation. When writing, the writer uses plain text as opposed to the formatted text found in “What You See Is What You Get” word processors like Microsoft Word.  The writer uses markup tagging conventions to define the general structure of a document (such as article, book, and letter), to stylise text throughout a document (such as bold and italics).

Markdown

Markdown is a lightweight markup language (LML). Markdown is a text-to-HTML conversion tool for web writers in easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML.

Markdown’ comprises the following:

1. A plain-text formatting syntax
2. A software tool that converts the plain text formatting to HTML

Note
You can use Markdown, GitHub and eventually generate static web pages using Jekyll.

Why markdown is popular?

Markdown is preferred in a software development environment, to keep the whole development team in one platform, so that the developers and documentation team can contribute and coordinate together without choosing a different documentation tool for the product delivery.

In the following image, GitHub shows the Markdown content in the workspace and the Html preview in the right pane.

Note
People familiar with HTML might realize that once the content in the document is associated with HTML tags, the document becomes difficult to read unless converted or previewed in the browser. Reading a Markdown document is easy because the content tagged with the markdown, still provide easy readability without any high level of distraction.

Following code snippet shows the difference between HTML and Markdown:

HTML Snippet

<h1>Why <em>you</em> should use Markdown to write your next blog post</h1>

<p><a href=”http://daringfireball.net/projects/markdown/”>Markdown</a> is just so dang legible, it will make your <em>whole life</em> easier. <strong>I promise.</strong></p>

Markdown Snippet

# Why *you* should use Markdown to write your next blog post

[Markdown][1] is just so dang legible, it will make your *whole life* easier. **I promise.**

[1]: http://daringfireball.net/projects/markdown/basics

Create Markdown using Document360 Integrated Markdown Editor

The Document360 Editor screen displays the Markdown editor on the left pane and the document preview on the right pane. The Markdown syntaxes are automatically incorporated in the editor depending on your determined activity.

When you drag-and-drop images or URL links in to the document, appropriate Markdown code related to the dropped image and the types URL are automatically tagged within the content.

Document360 provides two types of editors:

• · Markdown Editor: For text-based document and can also include code blocks.
• · WYSIWYG (HTML): Video, image and text document

The following images shows the Markdown Editor Toolbar and the Document360 interface, which can help you create markdown content.

Note:
Document360, recommends that you adapt to the Markdown editor so that you can quickly create structured editing using the tool bar and the integrated style sheet for maintaining and managing the consistent look and feel within the document.

Initially, it may take time to understand and adjust to the Markdown language syntaxes, but once you achieve proficiency, it becomes easier to apply appropriate syntaxes to the associated content. Document360 provides a couple of tools, such as Markdown Shortcut and Toolbar Editor.

Following is the list of Markdown Shortcut and commonly used syntax

For comparison between document-Markup languages, refer to the following Wikipedia link: https://en.wikipedia.org/wiki/Comparison_of_document-markup_languages

Also Read: Top 20 Software Documentation Tools

An intuitive knowledge base software to easily add your content and integrate it with any application. Give Document360 a try!

Get Started