{"id":13553711,"url":"https://github.com/briandominick/codewriting","last_synced_at":"2025-04-03T05:31:27.609Z","repository":{"id":48738418,"uuid":"90814425","full_name":"briandominick/codewriting","owner":"briandominick","description":"Source for Codewriting (book) and the Codewriting/Code the Docs (site/blog)","archived":false,"fork":false,"pushed_at":"2022-10-06T09:11:33.000Z","size":13932,"stargazers_count":50,"open_issues_count":28,"forks_count":13,"subscribers_count":11,"default_branch":"master","last_synced_at":"2024-11-04T01:32:51.181Z","etag":null,"topics":["asciidoc","book","collaborative-editing","devops","docops","docs-as-code","documentation","documentation-toolchain","learning-by-doing","markup","open-authoring","open-source","self-publishing"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/briandominick.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-05-10T02:55:13.000Z","updated_at":"2024-08-31T02:34:24.000Z","dependencies_parsed_at":"2023-01-19T10:15:38.075Z","dependency_job_id":null,"html_url":"https://github.com/briandominick/codewriting","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/briandominick%2Fcodewriting","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/briandominick%2Fcodewriting/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/briandominick%2Fcodewriting/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/briandominick%2Fcodewriting/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/briandominick","download_url":"https://codeload.github.com/briandominick/codewriting/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246944377,"owners_count":20858773,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asciidoc","book","collaborative-editing","devops","docops","docs-as-code","documentation","documentation-toolchain","learning-by-doing","markup","open-authoring","open-source","self-publishing"],"created_at":"2024-08-01T12:02:31.703Z","updated_at":"2025-04-03T05:31:22.596Z","avatar_url":"https://github.com/briandominick.png","language":"JavaScript","readme":"= Codewriting: Collaborative Documentation Ops for the Agile Age\n:page-permalink: /readme\n:page-layout: page\n// tag::global-settings[]\n:codewriting_source_uri: https://github.com/briandominick/codewriting\n:codewriting_www_uri: https://www.codewriting.org\n:liquidoc_www_uri: https://www.ajyl.org/liquidoc-cmf\n:ajyl_www_uri: https://www.ajyl.org\n:toc: macro\n// This README file serves as canonical source for some text and other code.\n// Denoted by specially formatted comments like the tag:: and end:: references\n// above and below this comment. These are hidden macros that enable me to mark\n// sections of a file for selective inclusion (think of it as embedding) into a\n// parent file elsewhere in my source repo during parsing.\n// end::global-settings[]\n\ntoc::[]\n\n// tag::preamble[]\n_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.\n\nA manual for establishing optimal documentation environments, _Codewriting_ explores the “docs-as-code” or “DocOps” approach to documenting and instructing software.\nThis 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.\n\nAs 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 (\u003c\u003ccreative-commons,see the Creative Commons ShareAlike license\u003e\u003e).\n\n_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.\nCoders 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.\nFrom 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.\n// end::preamble[]\n\n== Repo\n\nThe `briandominick/codewriting` repo contains much more than just the _Codewriting_ book source.\nThis is also the home of link:http://codewriting.org/[codewriting.org], which includes a blog and informational pages about DocOps tools and techniques.\nAll of this is built from a fairly robust codebase mixing mostly YAML and AsciiDoc files, configured to be processed by powerful build/publish tools.\nThis 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.\nPlease, be my guest, and modify to your heart's content.\n\nThese tools include:\n\n* link:http://https://jekyllrb.com/[Jekyll], a popular static site generator\n* link:http://asciidoctor.org/[Asciidoctor] parsing engine for AsciiDoc files\n* link:{liquidoc_www_uri}[LiquiDoc], my own tool, which I use for preprocessing YAML data and configuring complicated build procedures\n* link:https://git-scm.com/[Git] -- if you don't know it yet, the time has come\n\n[NOTE]\n.Do Not Be Intimidated\nMost 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.\nFirst, you do not have to know any Ruby to use these tools.\nMoreover, they will help you become comfortable using Bash shell utilities and command prompts generally.\nIf 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.\n\n== Build\n// tag::build-cw[]\nThe book and website are written in lightweight markup languages.\nThat means content starts as source code, which must be _compiled_ to a cohesive document in a friendlier format for reading.\n*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.\n\n_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.\nHere is how.\n\nIn order to operate the publishing tool included in this repo, you'll need Ruby.\nIf you're on a *Mac OSX or Linux* system, you likely have an appropriate version of Ruby installed.\n\nFor *Windows*, download and run link:http://rubyinstaller.org/[RubyInstaller].\n\n[TIP]\n.Git FTW\n--\nTo really engage with this book, you will want to use Git.\nTo set up Git, go to the link:https://git-scm.com/downloads[Git downloads page] and select your operating system.\n\nIf you are brand new to Git, check out link:https://try.github.io/levels/1/challenges/1[GitHub's Try Git tutorial].\n--\n\nThe 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]).\n\n. In the terminal, navigate to a workspace directory.\n+\n.Example (any directory will do)\n[source,shell]\n----\ncd Documents/workspace\n----\n\n. Clone this repo.\n+\n[source,shell]\n----\ngit clone git@github.com:briandominick/codewriting.git\n----\n+\n[TIP]\nIf 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.\n\n. Change directory to the repo.\n+\n[source,shell]\n----\ncd codewriting\n----\n\n. Run Bundler's install command to establish local Ruby gem dependencies.\n+\n[source,shell]\n----\nbundle install\n----\n+\nIf Bundler is not installed, run `gem install bundler`, then repeat this step.\nBundler is a package manager for Ruby gems; it will ensure you always have the right dependencies installed.\n\n. Build the book in PDF and HTML, as well as the site and my resumé.\n+\n[source,shell]\n----\nbundle exec liquidoc -c _configs/build-global.yml\n----\n\nNow 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.\nPlease give this latest draft a read and let me know what you think!\nThe other contents of `_build/` are yours to peruse.\nAlso check out the files in `_configs/`, `data/`, and `_templates/`, as well as all the AsciiDoc files in `book-cw/`.\n\n[TIP]\n--\nTo learn more about the build tool, explore the files in the link:https://github.com/briandominick/liquidoc-gem[LiquiDoc] repo!\nThis is my first ever Ruby scripting project; it's not terribly complex, and there's lots more to come.\n--\n\nYou can also perform a Jekyll build/serve operation against the `_build/` directory.\nTo do so using the included Jekyll config, still from the root directory:\n\n[source,shell]\n----\nbundle exec jekyll serve --config _configs/jekyll.yml --no-watch --skip-initial-build\n----\n\nNow browse to `http://127.0.0.1:4004` -- you should see the `codewriting.org` website.\n\n*To keep updated*, link:https://github.com/briandominick/codewriting/subscription[follow this repo on GitHub].\n// end::build-cw[]\n\n[NOTE]\nFor more about the build scripts and the overall framework (what goes where), see \u003c\u003cframework-and-build,Framework and Build\u003e\u003e below or check out link:{ajyl_www_uri}[LiquiDoc CMF directly].\n\n== Contribute\n// tag::contribute-cw[]\n*All proposed edits and additions are eagerly welcomed.*\n\n=== What to Contribute\n\nHere are some forms of content contributions I would love to receive:\n\nquotations::\nQuote yourself as if I interviewed you for three hours and kept some of your best advice.\nWrite yourself right into the text, either with an outright quote or a paraphrase.\n\nguest blocks::\nMake a text block that conveys your commentary on a topic, in context.\n\n=== Guest Block Syntax \u0026 Guidance\n\nThe two main types of block contributions are admonition blocks (either generic or branded) and guest sidebars, for longer prose.\n\nadmonition block::\n+\n--\nYou 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.\nAdmonition blocks should be kept to one short paragraph, at most.\n\ngeneric admonition::\n\n[source,asciidoc]\n----\n[TIP]\nHere is my opinion about this topic.\n----\n\nbranded admonition::\n\n[source,asciidoc]\n----\n[BRANDED.yourGHusername]\nI'll make this do something cool by the time we “go to press”.\n----\n\nIn this case, also place a 150x150 pixel PNG file to use as an avatar for you.\nMake it your headshot or a caricature or some symbol you want to rep your mug.\nName it `yourGHusername.png` and place it in `book-cw/images/avatars`.\n\n--\n\nguest sidebar::\n\nMake a sidebar for multi-paragraph contributions.\n+\n[source,asciidoc]\n----\n[guest_contribution]\n.Your Sidebar's Clever Title\n****\nHere is the text of your sidebar.\nKeep it witty, and remember to use one-sentence-per-line and other styles from the Style Guide.\n\nYou can use paragraphing, images, tables, and so forth.\nJust keep it tidy, witty, and informative.\n\n-- Tag Yourself (link:https://twitter.com/@memememe[memememe])\n****\n----\n\nTo make these items most modular, it is best that you contribute them in their own `filename.adoc` file.\nYour pull request is welcome to also incorporate the `include::filename.adoc[]` macro in the place you think your content best fits.\nOtherwise, it's fine to leave it for me to suggest a placement.\n\n=== How to Contribute\n\nHere are the technical steps to contributing.\nIf you don't know how to use Git or AsciiDoc yet, you may wish to *read the book before trying to contribute*.\nIn fact, that's a good general recommendation, so you don't duplicate something that's already included, and so you can enhance existing content -- even by contradicting it sensibly.\n\n. Fork the GitHub repo.\n\n. Create a branch.\n\n+\nIf you clone your newly forked repo to your local machine (similarly to the procedure for cloning _this_ repo, above), use `git checkout -b new-branch`, where `new-branch` is a descriptive name for your contribution (e.g., `sidebar-hacking`).\n\n. Edit the appropriate AsciiDoc file, or create and properly include a new one.\n\n. Build locally to make sure your contribution builds as both PDF and HTML.\n\n. Issue a pull request to my repo. +\n{codewriting_source_uri}\n\n. I'll review your contribution and respond to it as soon as I can.\n\n[TIP]\nIf you wish to propose a contribution before you start writing/coding, create an Issue and label it `proposal`.\nI'll review it and let you know what I think.\n\n=== Editorial Process\n\nOnly 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.\nOne of the commits in your first PR should add yourself to the appropriate contributors' list in `book-cw/frontmatter/acknowledgements.adoc`.\n\nI 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.\nAs a journalist in my past life, I was fanatical about attribution, accuracy, and integrity in news media.\nAs evidence, I submit  link:http://newstandardnews.net/contributors/handbook_v2.0.pdf[this journalism guide]) I helped write.\nI assure you I take proper representation and credit very seriously.\n// end::contribute-cw[]\n\n== Plans for Codewriting\n\nWords!::\nLots more content coming, across several chapters\n\nSlides!::\nI 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.\nI hope others will modify them to their liking and make use of them spreading the word about DocOps!\n\nExercises::\nI am working on a narrative about a docs-focused startup that hires the reader as Employee #3.\nHijinks ensue.\n\n[[framework-and-build]]\n== Framework and Build\n\nHere are some notes on what goes where and how it's all built.\n\n[source,ascii]\n----\n├── _build/ \u003c1\u003e\n│   └── publish/\n├── _configs/ \u003c2\u003e\n│   ├── asciidoctor.yml\n│   ├── build-global.yml\n│   └── jekyll.yml\n├── _posts/ \u003c3\u003e\n├── _templates/ \u003c4\u003e\n│   └── liquid/\n├── assets/ \u003c5\u003e\n├── book-cw/ \u003c6\u003e\n│   ├── _configs/ \u003c7\u003e\n│   ├── _data/ \u003c8\u003e\n│   ├── \u003ccontent_directories\u003e/ \u003c9\u003e\n│   ├── includes/ \u003c10\u003e\n│   └── index-book-cw.adoc \u003c11\u003e\n├── data/ \u003c12\u003e\n│   ├── attributes.yml\n│   ├── dependencies.yml\n│   ├── glossary.yml\n│   ├── item-lists.yml\n│   └── dominick.yml\n├── pages/ \u003c13\u003e\n├── theme/ \u003c14\u003e\n├── Gemfile \u003c15\u003e\n├── LICENSE.md \u003c16\u003e\n└── README.adoc \u003c17\u003e\n----\n\n\u003c1\u003e The scratch directory in which all preprocessing files are handled and final artifacts located\n\u003c2\u003e Configuration files for build tools, including Asciidoctor, Jekyll, and LiquiDoc (`build-global.yml` instructs the main build routine)\n\u003c3\u003e Blog posts for the site\n\u003c4\u003e Templates used for prebuilding content files (no site theme or page structure)\n\u003c5\u003e Images, AsciiDoc includes, and other content used directly in output, possibly for multiple documents\n\u003c6\u003e Book content files; everything that goes _in_ the book\n\u003c7\u003e Build configurations for the book's precompiled source files\n\u003c8\u003e Data source files for the book, for building complex content\n\u003c9\u003e Discrete content files (topics, source samples, etc)\n\u003c10\u003e Snippets and partials for the book\n\u003c11\u003e The book's content map\n\u003c12\u003e Structured data files for the whole project (not just the book)\n\u003c13\u003e Site content that doesn't go in the book\n\u003c14\u003e Files used to style output for the whole site\n\u003c15\u003e The project's Ruby dependency collection\n\u003c16\u003e The Creative Commons license and description of what is covered\n\u003c17\u003e Whoa, that's like, the source for what you're reading right now...\n\n=== Production Deployment\n\nAs of January 2019, link:https://www.codewriting.org[Codewriting.org] is built and served by link:https://www.netlify.com/[Netlify].\nNetlify's free service is simply amazing; I cannot recommend it strongly enough.\nAll I do is point it to the repo, enter the build command, and tell it where to get the built files to serve.\nNelify inegrates automatically with GitHub and analyzes the site output for security and integrity.\nAll this pretty much out of the box, with free HTTPS and custom domain-name handling.\n\n\n== Legal Stuff\n\nThe Codewriting codebase is covered by the \"Creative Commons ShareAlike 3.0 Unported\" license, except as noted in the link:NOTICE.md[NOTICE] of third-party software dependencies.\nYou are encouraged to copy and modify this content for your own purposes; just please link back to link:{codewriting_www_uri}/[codewriting.org].\nFor details, see link:{codewriting_source_uri}/blob/master/LICENSE.md[`LICENSE.md`] for full details and complete license text.\n","funding_links":[],"categories":["JavaScript","documentation"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbriandominick%2Fcodewriting","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbriandominick%2Fcodewriting","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbriandominick%2Fcodewriting/lists"}