Codewriting: Collaborative Technical Documentation for the Agile Age

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

A manual for establishing optimal documentation environments, Codewriting explores the “docs-as-code” or “DocOps” approach to documenting and instructing software. This iteratively written, open-source volume explores the unconventional strategies in use by many of today’s hottest startups and teams at several tech-industry stalwarts.

As a living, collaborative document, Codewriting employs many of the techniques it teaches — written in lightweight markup code, this book’s codebase (its text) can be forked and modified by anyone for any reason (see the Creative Commons ShareAlike license).

Codewriting is for the tech writer and engineer alike, and it covers systems that involve everyone in the development circle, such as DevOps, project management, and product ownership. Coders and writers will find advice for integrating the others' skills and tools for building better docs, as well as improved collaboration around docs and interfaces, user- and developer-facing alike. From writing and docs-planning techniques to blending the product’s build and content source, Codewriting is about upgrading how we communicate the products we make.

Build

This book is being written in a lightweight markup language. That means it starts as source code, and it must be compiled to a cohesive document in a friendlier format for reading.

Codewriting is totally free, and the latest public draft will always be made available here — all you have to do is pull the source repository and run a simple command to build a 1-page HTML page or PDF document. Here is how.

In order to operate the publishing tool included in this repo, you’ll need Ruby. If you’re on a Mac OSX or Linux system, you likely have an appropriate version of Ruby installed.

For Windows, download and run RubyInstaller.

Warning

The packaged scripts have not yet been tested on Windows. Instructions below assume Mac OS or Linux.

To really engage with this book, you will want to use Git. To set up Git, go to the Git downloads page and select your operating system.

If you are brand new to Git, check out GitHub’s Try Git tutorial.

The last tool you need is your preferred terminal/command prompt.

1. In the terminal, navigate to a workspace directory.

   cd ~/Documents/workspace

2. Clone this repo.

   git clone git@github.com:briandominick/codewriting.git

   Tip	If you don’t wish to run Git and clone the repo, you can always download and unzip the archive of this repo anywhere on your hard drive.

3. Change directory to the repo.

   cd codewriting

4. Install the Bundler gem.

   gem install bundler

   This is a special package manager for Ruby gems; it will ensure you always have the right dependencies installed.

5. Run Bundler’s install command to establish local Ruby gem dependencies.

   bundle install

6. Make the build and parse scripts executable.

   MacOS/Linux Example

   chmod 755 scripts/publish.rb
   chmod 755 scripts/liquidoc.rb

   Tip	For Windows environments, perhaps try the most appropriate solution from this Stack Overflow Q/A.

7. Build the book in PDF and HTML.

   bundle exec scripts/publish.rb -i index-book.adoc -o codewriting-book-draft -l

Now you can open _output/codewriting-book-draft.html in your preferred browser or open _output/codewriting-book-draft.pdf in your favorite PDF viewer. Please give this latest draft a read and let me know what you think!

Tip	To learn more about the build tool: bundle exec scripts/publish.rb --help bundle exec scripts/liquidoc.rb --help Or explore the files in the repo!

To keep updated, follow this repo on GitHub.

Note	For more about the build scripts and the overall framework (what goes where), see Framework and Build below.

Contribute

All proposed edits and additions are eagerly welcomed.

What to Contribute

Here are some forms of content contributions I would love to receive:

quotations

Quote yourself as if I interviewed you for three hours and kept some of your best advice. Write yourself right into the text, either with an outright quote or a paraphrase.

guest blocks

Make a text block that conveys your commentary on a topic, in context.

Guest Block Syntax & Guidance

The two main types of block contributions are admonition blocks (either generic or branded) and guest sidebars, for longer prose.

admonition block

You can either author a generic admonition, to be credited in the Acknowledgements and the Git repo, or you can brand an admonition with your name (or GH username) and mug. Admonition blocks should be kept to one short paragraph, at most.

generic admonition

[TIP]
Here is my opinion about this topic.

branded admonition

[BRANDED.yourGHusername]
I'll make this do something cool by the time we “go to press”.

In this case, also place a 150x150 pixel PNG file to use as an avatar for you. Make it your headshot or a caricature or some symbol you want to rep your mug. Name it yourGHusername.png and place it in book-cw/images/avatars.

guest sidebar

Make a sidebar for multi-paragraph contributions.

[guest_contribution]
.Your Sidebar's Clever Title
****
Here is the text of your sidebar.
Keep it witty, and remember to use one-sentence-per-line and other styles from the Style Guide.

You can use paragraphing, images, tables, and so forth.
Just keep it tidy, witty, and informative.

-- Tag Yourself (link:https://twitter.com/@memememe[memememe])
****

To make these items most modular, it is best that you contribute them in their own filename.adoc file. Your pull request is welcome to also incporporate the include::filename.adoc[] macro in the place you think your content best fits. Otherwise, it’s fine to leave it for me to suggest a placement.

How to Contribute

Here are the technical steps to contributing. If you don’t know how to use Git or AsciiDoc yet, you may wish to read the book before trying to contribute. In fact, that’s a good general recommendation, so you don’t duplicate something that’s already included, and maybe you should be enhancing existing content.

1. Fork the GitHub repo.

2. Create a branch.

3. Edit the appropriate AsciiDoc file, or create and appropriately include a new one.

4. Build locally to make sure your contribution builds as both PDF and HTML.

5. Issue a pull request to my repo.
   https://github.com/briandominick/codewriting

6. I’ll review your contribution and respond to it as soon as I can.

Tip	If you wish to propose a contribution before you start writing/coding, create an Issue and label it proposal. I’ll review it and let you know what I think.

Editorial Process

Only once 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 log for all eternity. One of the commits in your first PR should add yourself to the appropriate contributors' list in book-cw/frontmatter/acknowledgements.adoc.

I do reserve the right to include lessons from your contributions even if we cannot agree on the specific final text; any particular ideas reflected will be duly credited. As a journalist in my past life, I was fanatical about attribution, accuracy, and integrity in news media. As evidence, I submit this journalism guide) I helped write. I assure you I take proper representation and credit very seriously.

Plans for Codewriting

Words!

Lots more content coming, across several chapters

Slides!

I want to make a bulleted summary of each chapter/section as a "slide", which can be included in each section as well as compiled into a slide deck for presentations. I hope others will modify them to their liking and make use of them spreading the word about DocOps!

Site!

I’ve purchased codewriting.org and will eventually build a static site there, including a landing page, a blog, and lots of side resources.

Framework and Build

Here are some notes on what goes where and how it’s all built.

_data: # (1)
_layouts: # (2)
assets: # (3)
  images:
book-cw: # (4)
  _configs: # (5)
    backmatter.yml
  _data: # (6)
    bibliography.yml
    glossary.yml
  includes: # (7)
  part-directories:
scripts: # (8)
  liquidoc.rb
  publish.rb
theme: # (9)
  fonts:
  pdf-theme.yml
Gemfile # (10)
index-book.adoc # (11)

1. Global data source files, not specific to Codewriting book

2. Liquid templates for mapping data to variables in precompiled files

3. Images and other content used directly in output

4. Book content files; everything that goes in the book

5. Build configurations for the book’s precompiled source files

6. Data source files for the book, for building complex content

7. Discrete content files (topics, source samples, etc)

8. The build scripts (publish.rb and liquidoc.rb)

9. Files used to style output; hopefully these will evolve to consolidate across media

10. The project’s Ruby dependency collection

11. The book index (document map)

Legal Stuff

The Codewriting codebase is covered by two licenses: MIT for functional code; "Creative Commons ShareAlike 3.0 Unported" for content. For details, see LICENSE.md for full details and complete license text.