Documenting Our Work

Submitted by damar on Thu, 07/13/2017 - 09:04

Damar Thapa

MaaDi's

Legal Notice

Copyright © 2017 | DT's Den |
Disclaimer: I provide no warranty of any kind, express or implied, that the information provided is complete, accurate, and reliable. So, you use the information at your own risk.

Abstract

In this article, I am documenting (in brief) the software applications, tools, and approaches I have used since the early 90s to document my work and study. I do not claim that the approaches I have chosen are the best for everyone and every occasion. They were, still are, influenced by my own taste, my strengths and weaknesses in the field, solutions available at the time, or, in most cases, to go along with the members/organisations I was working with.
I have a feeling, however, that if I had started my computer journey on a system with Graphical User Interfaces (GUIs) and clicking devices, not on terminals, my choices, possibly, would have been different.

1. Introduction

Documentation is an essential part of any engineering projects. And, its importance in IT projects, where most parts are intangible, cannot be overstressed.
In this article I am documenting some of the software applications I used, some I am still using, to document my projects.

2. My First Documentation Project with vi Text Editor

In early 90s, as a part of a computing course, I got exposed to Unix System and its vi text editor. In the course, we had to complete a simple database project, and use vi editor to document it (possibly, the system only had vi editor) . Since I only had used MS-DOS (Microsoft Disk Operating System) back then and no proper tutorial was provided on using vi, it was not a comfortable experience.
When I looked back, all I had done to complete the documentation were:
  • Type 'vi fileName.txt' to open the file with vi
  • 'Esc' key to toggle between comand and insert mode
  • Type ':w' to 'save'
  • Type ':q' to quit
  • Cursor movement and insert/delete, etc.
In 1998/99, I revisited 'vi' editor once again, after moving to Linux Operating System, but I did not stick with it. There were other choices, like pico, emacs etc. I am using Emacs to write this document.

3. WordStar: First Word Processor Software

WordStar was my first word processor software experience, before vi text editor. Intuitive and powerful, but I never got a chance to use on any project or commercial use.

4. WordPerfect 5.1

The WordPerfect 5.1 was my first word processor software that I got proper training, used it on my job, provided support, and was comfortable using macros.
I used WordPerfect under MS-DOS and briefly under Unix-SCO systems. Since I knew the shortcut keys -- commands to make WordPerfect to perform certain tasks -- I found it very efficient. It was reliable and powerful.

5. Microsoft Office 97 (MS office)

As Microsoft Office started dominating the market, I moved to Microsoft Office 97 in 1998 . It was the best office product I ever used -- an easy to use product with full of features.
As Microsoft released MS Office 2000, I started feeling the cost of licensing and format incompatibility hassle between two versions unpalatable.
As more and more people started circulating office files in Office 2000 format, I made the decision of not using the MS Office product.

6. So, search for MS Office alternative began

I was happy with MS Office 97 in terms of its features, ease of use, power, and reliability. The problem came on two fronts, and they were, as indicated above:
  • Format incompatibility: Microsoft provided conversion tools were alright to make files compatible, but it was an extra hassle. And, I felt diminished to have the older version (possibly, a young man's ego!
  • Licensing Cost: Near HK$3,000.00 for the Office 97 suite was, possibly, reasonable, considering the features it provided and the applications that came with the bundle. But, as a personal user, whose daily usage required no more than basic features, the cost was not justifiable.
In the subsequent sections, I will list some of the software applications I tried (some I still use) as my replacement for MS Office product.

7. StarOffice Suite

I purchased the StarOffice Suite for Linux Operating Systems for just over HK$250.00, a fraction of what I had to pay for MS Office Suite. It was not as feature-rich as MS Office, but it had enough features that majority of office users needed on a daily basis. It was better suited for personal and small business users.

8. OpenOffice Suite

The Sun Microsystem bought StaffOffice Suite from Star-Division in 1999. On 19 July 2000, it announced its decision to release the source code of the StarOffice Suite to the open source community under the GNU General Public License (GPL), and the formation of OpenOffice.org to coordinate the source and further development.
It was a big news for the Open Source community to be able to have a full-fledged Office suite under its ownership. Currently, the OpenOffice Suite has been developed under:

9. DocBook

DocBook is an Extensible Markup Language (XML) standard designed for authoring documents. XML is a markup language, a subset of the Standard Generalised Markup Language (SGML).
The following is the diagram -- direct link from The Linux Documentation Project -- showing the working of DocBook:
  • Authors create structured documents -- XML Source.
  • When an XML source is passed to the formatter, represented by dotted box in the diagram:
    • It ensures that XML source is valid using Docbook's Data Type Definition (DTD), and
    • It generates the targetted output (PDF, HTML, EPUB, etc.) using the provided stylesheet.
With the above working mechanism, an author can create a structured document without considering its presentation (style) and intended formats. The document styling can be done separately, if needed, by professionals. This separation of document content from its styling allows writers and designers to work independently from each other.
DocBook standard is widely used by Open Source communities, such as Linux Documentation Project, FreeBSD Documentation Project, GNOME Documentation Project, Red Hat, etc.

10. LaTeX

LaTeX is another powerful document prepartion system for high-quality typesettings. Like DocBook, it "encourages authors not to worry too much about the appearance of their documents but to concentrate on getting the right content", and leave document design part to document designers.
Latex source file has the extension of .tex, and it contains content in simple text, and latex markups/commands.
One example latex source file:
\documentclass{article}
\title{Cartesian closed categories and the price of eggs}
\author{Jane Doe}
\date{September 1994}
\begin{document}
\maketitle
 Hello world!
\end{document}
The latex commands/tags in the above source code are mostly self explanatory. For example, it has declared the documentclass, title, author, date, etc. This particular document is an article. Other possible documentclass could be book, letter, slide, report, etc.
Once the source file is ready, it is compiled into PDF, or postcript, file using latex command.
Latex is very popular in academia, writing reports, articles, letters, thesis, books, etc.

11. Lynx

Lyx is a document processor, based on TeX/LaTeX, that, according to official lyx site, "encourages an approach to writing based on the structure of your documents (WYSIWYM) and not simply their appearance (WYSIWYG)."
For those who do not know latex and do not want to learn, Lyx could work for them.

12. ASCIIDoctor

I recently stumbled on ASCIIDoctor when I was looking for easier options to make notes while listening to a lecture or reading. According to ASCIIDoctor website:
AsciiDoc is two things:
  • A mature, plain-text writing format for authoring notes, articles, documentation, books, ebooks, web pages, slide decks, blog posts, man pages and more.
  • A text processor and toolchain for translating AsciiDoc documents into various formats (called backends), including HTML, DocBook, PDF and ePub.
The following is a simple ASCIIDoctor document:
= Hello, AsciiDoc!
Doc Writer <doc@example.com>
== First Section
    * item 1
    * item 2
[source,ruby]
    ----
    print "Hello, World!"
    ----
The above block of asciidoc code generates the following HTML output:
One thing I like about ASCIIDoctor is its lightweight markups, something one can manage to include while taking fast notes. DocBook, HTML and LaTex are too verbose for that purpose.

13. Summary

In the pursuit of finding an MS Office alternative document preparation system, I was seeking the following criteria:
  • The document content (source) and document styling should be independent from each other;
  • The source has to be simple text files so that any text editor should be able to open and edit;
  • System itself has to be plaftorm neutral, or supported by major operating systems; and
  • Open source, or freely available.
Only DocBook and LaTex fulfilled all above criteria. AsciiDotor seems promising, but I am still new to this system.
My choice of LaTex and DocBook was more of going back to the old school -- create a source, set its style, and compile to generate the output, manually. It is an extra work, and there is a learning curve for both systems. If you are, however, working on big documents, like books, reports, thesis, etc., Office products, including Microsoft Office, cannot win.
That was my decision based on my requirement, my skill background and the products available at the time. Since every person has his/her own requirement and strength, you have to find your best yourself. If you have access to Ms Office product or any related product, have mastery/enough skills in using it, and do not know what LaTex and DocBooks are, your winning decision should be to stay with your existing product.
Since all products are getting better in terms of output quality and features, our skills play bigger roles in choosing a product than the product itself. This was not the case in 90s and early 2000s when I made my decisions!
Lastly, as our contents are more likely to go online than on printed material, I am leaning towards HTML5 and DocBook.

A. Revision History

Revision History
Revision 0.0-0 Thu, 13 July 2017 Damar Thapa
category
com_gen