Codewriting

= Codewriting: Collaborative Documentation Ops for the Agile Age :page-permalink: /readme :page-layout: page // tag::global-settings[] :codewriting_source_uri: https://github.com/briandominick/codewriting :codewriting_www_uri: https://www.codewriting.org :liquidoc_www_uri: https://www.ajyl.org/liquidoc-cmf :ajyl_www_uri: https://www.ajyl.org :toc: macro // This README file serves as canonical source for some text and other code. // Denoted by specially formatted comments like the tag:: and end:: references // above and below this comment. These are hidden macros that enable me to mark // sections of a file for selective inclusion (think of it as embedding) into a // parent file elsewhere in my source repo during parsing. // end::global-settings[]

toc::[]

// tag::preamble[] 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, this book's codebase (its text) can be forked and modified by anyone for any reason other than direct profit (<<creative-commons,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, quality assurance, 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. // end::preamble[]

== Repo

The briandominick/codewriting repo contains much more than just the Codewriting book source. This is also the home of link:http://codewriting.org/[codewriting.org], which includes a blog and informational pages about DocOps tools and techniques. All of this is built from a fairly robust codebase mixing mostly YAML and AsciiDoc files, configured to be processed by powerful build/publish tools. This repo can serve as a framework on which to base your own site with a self-contained build operation for turning complex source and data into a professional web presence, all using free, open source tools. Please, be my guest, and modify to your heart's content.

These tools include:

• link:http://https://jekyllrb.com/[Jekyll], a popular static site generator
• link:http://asciidoctor.org/[Asciidoctor] parsing engine for AsciiDoc files
• link:{liquidoc_www_uri}[LiquiDoc], my own tool, which I use for preprocessing YAML data and configuring complicated build procedures
• link:https://git-scm.com/[Git] -- if you don't know it yet, the time has come

[NOTE] .Do Not Be Intimidated Most of these tools happen to be sourced in Ruby and run primarily in a Ruby environment using each tool's built-in command-line interface. First, you do not have to know any Ruby to use these tools. Moreover, they will help you become comfortable using Bash shell utilities and command prompts generally. If you want to learn more about how these tools work, we'll be exploring LiquiDoc, Jekyll, and several tools from the Asciidoctor ecosystem, as well as many others, all in these pages.

== Build // tag::build-cw[] The book and website are written in lightweight markup languages. That means content starts as source code, which must be compiled to a cohesive document in a friendlier format for reading. If you try merely reading it as file pages on GitHub, you'll be missing a lot, even though GitHub plays somewhat nice with AsciiDoc.

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 link:http://rubyinstaller.org/[RubyInstaller].

[TIP] .Git FTW

To really engage with this book, you will want to use Git. To set up Git, go to the link:https://git-scm.com/downloads[Git downloads page] and select your operating system.

If you are brand new to Git, check out link:https://try.github.io/levels/1/challenges/1[GitHub's Try Git tutorial].

The last tool you need is your preferred terminal/command prompt (link:https://www.lifewire.com/how-to-open-command-prompt-2618089[Windows instructions], link:http://www.wikihow.com/Get-to-the-Command-Line-on-a-Mac[Mac instructions]).

. In the terminal, navigate to a workspace directory. + .Example (any directory will do) [source,shell]

cd Documents/workspace

. Clone this repo. + [source,shell]

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 link:https://github.com/briandominick/codewriting/archive/master.zip[the archive of this repo] anywhere on your hard drive, then continue these instructions.

. Change directory to the repo. + [source,shell]

cd codewriting

. Run Bundler's install command to establish local Ruby gem dependencies. + [source,shell]

bundle install

If Bundler is not installed, run gem install bundler, then repeat this step. Bundler is a package manager for Ruby gems; it will ensure you always have the right dependencies installed.

. Build the book in PDF and HTML, as well as the site and my resumé. + [source,shell]

bundle exec liquidoc -c _configs/build-global.yml

Now you can open _build/publish/codewriting-book-draft.html in your preferred browser or open _build/publish/codewriting-book-draft.pdf in your favorite PDF viewer. Please give this latest draft a read and let me know what you think! The other contents of _build/ are yours to peruse. Also check out the files in _configs/, data/, and _templates/, as well as all the AsciiDoc files in book-cw/.

[TIP]

To learn more about the build tool, explore the files in the link:https://github.com/briandominick/liquidoc-gem[LiquiDoc] repo! This is my first ever Ruby scripting project; it's not terribly complex, and there's lots more to come.

You can also perform a Jekyll build/serve operation against the _build/ directory. To do so using the included Jekyll config, still from the root directory:

[source,shell]

bundle exec jekyll serve --config _configs/jekyll.yml --no-watch --skip-initial-build

Now browse to http://127.0.0.1:4004 -- you should see the codewriting.org website.

To keep updated, link:https://github.com/briandominick/codewriting/subscription[follow this repo on GitHub]. // end::build-cw[]

[NOTE] For more about the build scripts and the overall framework (what goes where), see <<framework-and-build,Framework and Build>> below or check out link:{ajyl_www_uri}[LiquiDoc CMF directly].

== Contribute // tag::contribute-cw[] 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::

[source,asciidoc]

[TIP] Here is my opinion about this topic.

branded admonition::

[source,asciidoc]

[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. + [source,asciidoc]

[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 incorporate 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