Since starting my blogging career here at Hashnode, I have enjoyed the platform they offer. Honestly, though, I keep waiting for the other shoe to drop and have to pay a subscription in order to blog. Has not happened yet so a very big Kudos to Hashnode.
Hashnode has offered a boot camp in technical writing. I would like to argue the point that it is not exactly technical writing that one would be employed to do. I call it technical blogging. It was an informative course for bloggers but fell short for the professional writer. I had asked the instructor about style guides and received confusion. So I will explain a little about them here.
Technical writing is a highly coveted skill in the professional workplace such as Amazon, Boeing, Tesla, Red Hat, and almost every company that has a need to document processes, train, etc. Any good engineering team should adopt one and re-tool it to their needs.
Technical writing is the practice of documenting the processes, such as software manuals or instructional materials. Traditionally, it was limited to user manuals of some sort.
We, (as technical writers) use and strictly adhere to an editorial style guide when writing professionally. An editorial style guide defines an editorial group's guidelines for communication. For example, which of the following rules should your organization adopt for headings? If you do not use one then there are several you can choose from out in the wild. They all have very good guidance and offer unique guidelines.
The company Google has one that provides editorial guidelines for anyone writing developer documentation for Google-related projects.
The Microsoft Writing Style Guide provides guidelines for anyone writing technical documentation in general.
With the explanation of style guides out of the way, I would like to talk about AsciiDoc and DocBook styles. I would love feedback from those of you who work in these formats and gauge your likes and dislikes about them.
DocBook and Flamel
For the longest time, I have written my books and courses in DocBook. In fact, we still use it where I work with talk of moving to AsciiDoc on future projects.
This snippet from Wikipedia:
As a semantic language, DocBook enables its users to create document content in a presentation-neutral form that captures the logical structure of the content; that content can then be published in a variety of formats, including HTML, XHTML, EPUB, PDF, man pages, Web help, and HTML Help, without requiring users to make any changes to the source. In other words, when a document is written in DocBook format it becomes easily portable into other formats, rather than needing to be rewritten.
It has a very HTML like style to it and the tagging can get very obscure. The learning curve for new technical writers is slower than AsciiDoc and therefore they spend more time tagging and not writing. Unless of course, you have a style guide to follow and even then it is complicated to get formats correct. Everything needs to be in its place for a book to build.
DocBook Syntax Guide
AsciiDoc and AsciiDoctor
AsciiDoc is new to me. When I first started blogging and hosted my own server I wrote in AsciiDoc and converted to HTML when published. It was easy to write, easy to read. The tagging was not so bad that I needed to build it with AsciiDoctor to properly read it. I could read it straight from GitHub in a markdown format.
The AsciiDoc snippet from Wikipedia:
AsciiDoc is a human-readable document format, semantically equivalent to DocBook XML, but using plain-text mark-up conventions. AsciiDoc documents can be created using any text editor and read “as-is”, or rendered to HTML or any other format supported by a DocBook tool-chain, i.e. PDF, TeX, Unix man pages, e-books, slide presentations, etc. Common file extensions for AsciiDoc files are txt(as encouraged by AsciiDoc's creator) and adoc.
AsciiDoc has a very markup style to it and is easy to follow.
AsciiDoc Syntax Guide (from AsciiDoctor)
I would like a discussion on what you use and why you use it? Why does your company still use DocBook? What prompted the decision to move to AsciiDoc?
Is it more robust because it is much more mature than AsciiDoc?
What are the Pros and Cons?
