LaTeX is commonly thought of as a documentation technology used primarily in academia and science. With a bit of effort, however, it can be used to generate very high quality documentation for software or hardware products.
This series of articles show you how it can be done based on my experiences doing so for a number of clients.
I should be clear here about what we are trying to achieve. If you must use LaTeX for tech docs, doing so is not a easy as, say, DITA, but it can be done. It requires diving into the minutia of LaTeX packages, commands, options, arguments and so forth. You can start learning using the Quick Start Guide or jump over that and go directly to creating a documentation root file. I tried to make these topics linear. At the same time, you can use them as reference topics for specific problems you may have. But remembers, these topics are not the final word on using LaTeX for tech docs. The same resources I used are available for you. Google is your guide.
- Quick Start Guide
- A Very Brief Introduction to LaTeX
- Selecting a LaTeX Distribution and a LaTeX Editor
- Converting Source PDF Files to LaTeX Files
- Generating Output from a LaTeX File
- Creating a LaTeX Project File Structure
- Structuring a LaTeX Root File
- Using Input or Include Commands
- LaTeX Commands Syntax
- Selecting the Document Class
- About LaTex Stylesheets
- Adding writer2latex Conversion Packages to the Stylesheet
- Creating a Custom Title Page
- Setting Page Size, Margins and Layout
- Creating Custom Headers and Footers
- Writing Chapters and Appendices
- Creating Tables
- Creating Hypertext Links
- Defining and Using Colours
- Adding Font Selection Support and Defining Fonts
- Adding Multi-Lingual Support
- Setting URL Styles
- Setting Sectioning Styles and Packages
- Setting Line Spacing Package and Settings
- Formatting figure captions
- Customizing Lists and Indentation
- Setting Table-related Styles and Packages
- Setting Style Definitions for Note, Info, and Warning Boxes
- Some Experimental Stuff
- Sample LaTeX Root File
Quick overview to get you up and running in no time at all.
As the title says!
To write LaTeX files, you can use LaTeX editors, but you need a TeX distribution to build LaTeX files into an output such as PDF.
What if you only had PDF files as your source material? How do you convert them to LaTeX?
After creating a LaTeX file, It needs to be built using the TeX distribution to generate an output PDF file.
A best practice for a technical documentation project is to use a root file.
This topic provides a simplified root file.
In a root file, referencing chapter file can be done using either the include or the input commands
A (very) brief overview of LaTeX command syntax.
The documentclass command tells the LaTeX typesetter how to handle the document and which document package to use to typeset the output.
Use a stylesheet to easily maintain all the styles used by the document.
If writer2latex was used, these conversion packages will be included in the stylesheet
LaTeX has the capability of defining quite good looking title pages. Not easy, but doable.
Before customizing headers and footers, you should define the page size, margins and layout.
Using the fancyhdr package, you can create customized headers and footers.
Chapters in LaTeX require specific commands and use section headings which are pulled out into the Table of Contents
You can add simple to complex tables to a LaTeX document using several types of packages, depending on the requirements of the table.
When generating a PDF, you create clickable links using the hyperref package.
By setting colour definitions in the stylesheet, you can reference them throughout the stylesheet or in the document.
Define the base font for your document and font support for monospaced font and font size specifications.
Using the babel package.
Formatting URL styles.
Using the titlesec and sectsty packages.
Using the setspace package.
Using the lstlisting command with the listing package.
Using the enumitem package.
Using the supertabular package.
Creating a warnbox, notice and infobox.
Creating footnotes, widow/orphan control, and adding to do notes to code.
Putting it all together.