m0j0hn / codewriting-book

Code Writing: DocOps/Technical Writing Book

This is an open, collaborative writing project to document current best practices and forward thinking in the field of technical communications, specifically documentation for software projects.

Build

This book is being written in AsciiDoc. That means it starts as source code (in files with the .adoc extension), and it must be compiled to a more readable format.

Here is how to build a 1-page HTML document or a PDF booklet from the source, so you can read it in a proper format:

1. Install Asciidoctor.

2. Clone this repo.

   git clone https://github.com/briandominick/codewriting-book.git

3. cd codewriting-book

4. Build the book in PDF or HTML.

   1. For an HTML build:

      1. asciidoctor -d book index.adoc

      2. Open index.html in your preferred browser.

   2. For a PDF build (recommended):

      1. Install asciidoctor-pdf.

      2. asciidoctor -r asciidoctor-pdf -b pdf -d book index.adoc

      3. Open index.pdf in your favorite PDF viewer.

Contribute

All proposed edits and addition are eagerly welcomed. All contributions will be reviewed. Only when we’re both happy with the final state of a proposed change will I incorporate any of your work, and all contributors will be prominently credited, as well as remain in the git blame/log for all eternity. It’s lucky I’m too lazy to integrate this with a blockchain platform to verify commits against a cryptocurrency ledger.

I do reserve the right to include lessons from your contributions even if we cannot agree on the specific text; any specific ideas reflected will be duly credited.

For full details, build the book and see [collaborative-authorship].