Tools for Code Documentation
FAQ on Technical Writing
Code documentation is a process by which a programmer documents code. It is a well-known term among engineers. If they don’t do this, it leads to poor code readability and hard maintenance for other team members.
Code documentation is different from project documentation as it mainly aims at how the system works but these two processes have something in common — requirements of using a professional tool. In this article, I overview some popular tools for creating code documentation.
LaTex
LaTeX is a document preparation system for high-quality typesetting. It is most often used for medium-to-large technical or scientific documents but it can be used for almost any form of publishing.
LaTeX is not a word processor! Instead, LaTeX encourages authors not to worry too much about the appearance of their documents but to concentrate on getting the right content.
LaTeX is a high-quality typesetting system; it includes features designed for the production of technical and scientific documentation. LaTeX is the de facto standard for the communication and publication of scientific documents. LaTeX is available as free software.
You don’t have to pay for using LaTeX, i.e., there are no licence fees, etc.
Pandoc
Pandoc understands a number of useful markdown syntax extensions, including document metadata (title, author, date); footnotes; tables; definition lists; superscript and subscript; strikeout; enhanced ordered lists (start number and numbering style are significant); running example lists; delimited code blocks with syntax highlighting; smart quotes, dashes, and ellipses; markdown inside HTML blocks; and inline LaTeX. If strict markdown compatibility is desired, all of these extensions can be turned off.
There are many ways to customize Pandoc to fit your needs, including a template system and a powerful system for writing filters.
Pandoc includes a Haskell library and a standalone command-line program. The library includes separate modules for each input and output format, so adding a new input or output format just requires adding a new module.
Pandoc is free software, released under the GPL.
Markdown
Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).
The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. While Markdown’s syntax has been influenced by several existing text-to-HTML filters, the single biggest source of inspiration for Markdown’s syntax is the format of plain text email.
LiveEdu
LiveEdu allows you to broadcast your code documentation and create “Video code documentation.”
Education Ecosystem is a decentralized learning ecosystem that teaches professionals and college students how to build real products. You can describe our product as a hybrid of Pluralsight and Twitch. We are building the world’s biggest learning ecosystem for future technology topics such as artificial intelligence, cybersecurity, game development, data science, cryptocurrencies, and programming. Education Ecosystem is video based and each project contains videos, a structured project outline, project repo, and downloadable resources. Users can clone project resources from the Education Ecosystem Git and run the applications on their local machine.
Sphinx
Sphinx is a tool that makes it easy to create intelligent and beautiful documentation, written by Georg Brandl and licensed under the BSD license.
It was originally created for the Python documentation, and it has excellent facilities for the documentation of software projects in a range of languages. Here are some features:
- Output formats: HTML (including Windows HTML Help), LaTeX (for printable PDF versions), ePub, Texinfo, manual pages, plain text.
- Extensive cross-references: semantic markup and automatic links for functions, classes, citations, glossary terms, and similar pieces of information.
- Hierarchical structure: easy definition of a document tree, with automatic links to siblings, parents, and children.