diff --git a/.ruby-version b/.ruby-version index 860487c..be94e6f 100644 --- a/.ruby-version +++ b/.ruby-version @@ -1 +1 @@ -2.7.1 +3.2.2 diff --git a/Gemfile b/Gemfile index 6193a03..6656142 100644 --- a/Gemfile +++ b/Gemfile @@ -1,4 +1,3 @@ source "https://rubygems.org" gem "jekyll-theme-so-simple" -gem "html-proofer" diff --git a/Gemfile.lock b/Gemfile.lock index e70fe7e..6cbb1fc 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -1,71 +1,92 @@ GEM remote: https://rubygems.org/ specs: - addressable (2.8.0) - public_suffix (>= 2.0.2, < 5.0) + addressable (2.9.0) + public_suffix (>= 2.0.2, < 8.0) + base64 (0.3.0) + bigdecimal (4.1.1) colorator (1.1.0) - concurrent-ruby (1.1.9) - em-websocket (0.5.2) + concurrent-ruby (1.3.6) + csv (3.3.5) + em-websocket (0.5.3) eventmachine (>= 0.12.9) - http_parser.rb (~> 0.6.0) - ethon (0.14.0) - ffi (>= 1.15.0) + http_parser.rb (~> 0) eventmachine (1.2.7) - faraday (1.8.0) - faraday-em_http (~> 1.0) - faraday-em_synchrony (~> 1.0) - faraday-excon (~> 1.1) - faraday-httpclient (~> 1.0.1) - faraday-net_http (~> 1.0) - faraday-net_http_persistent (~> 1.1) - faraday-patron (~> 1.0) - faraday-rack (~> 1.0) - multipart-post (>= 1.2, < 3) - ruby2_keywords (>= 0.0.4) - faraday-em_http (1.0.0) - faraday-em_synchrony (1.0.0) - faraday-excon (1.1.0) - faraday-httpclient (1.0.1) - faraday-net_http (1.0.1) - faraday-net_http_persistent (1.2.0) - faraday-patron (1.0.0) - faraday-rack (1.0.0) - ffi (1.15.4) + faraday (2.14.1) + faraday-net_http (>= 2.0, < 3.5) + json + logger + faraday-net_http (3.4.2) + net-http (~> 0.5) + ffi (1.17.4) + ffi (1.17.4-aarch64-linux-gnu) + ffi (1.17.4-aarch64-linux-musl) + ffi (1.17.4-arm-linux-gnu) + ffi (1.17.4-arm-linux-musl) + ffi (1.17.4-arm64-darwin) + ffi (1.17.4-x86-linux-gnu) + ffi (1.17.4-x86-linux-musl) + ffi (1.17.4-x86_64-darwin) + ffi (1.17.4-x86_64-linux-gnu) + ffi (1.17.4-x86_64-linux-musl) forwardable-extended (2.6.0) - html-proofer (3.19.2) - addressable (~> 2.3) - mercenary (~> 0.3) - nokogumbo (~> 2.0) - parallel (~> 1.3) - rainbow (~> 3.0) - typhoeus (~> 1.3) - yell (~> 2.0) - http_parser.rb (0.6.0) - i18n (1.8.10) + google-protobuf (4.34.1) + bigdecimal + rake (~> 13.3) + google-protobuf (4.34.1-aarch64-linux-gnu) + bigdecimal + rake (~> 13.3) + google-protobuf (4.34.1-aarch64-linux-musl) + bigdecimal + rake (~> 13.3) + google-protobuf (4.34.1-arm64-darwin) + bigdecimal + rake (~> 13.3) + google-protobuf (4.34.1-x86-linux-gnu) + bigdecimal + rake (~> 13.3) + google-protobuf (4.34.1-x86-linux-musl) + bigdecimal + rake (~> 13.3) + google-protobuf (4.34.1-x86_64-darwin) + bigdecimal + rake (~> 13.3) + google-protobuf (4.34.1-x86_64-linux-gnu) + bigdecimal + rake (~> 13.3) + google-protobuf (4.34.1-x86_64-linux-musl) + bigdecimal + rake (~> 13.3) + http_parser.rb (0.8.1) + i18n (1.14.8) concurrent-ruby (~> 1.0) - jekyll (4.2.1) + jekyll (4.4.1) addressable (~> 2.4) + base64 (~> 0.2) colorator (~> 1.0) + csv (~> 3.0) em-websocket (~> 0.5) i18n (~> 1.0) - jekyll-sass-converter (~> 2.0) + jekyll-sass-converter (>= 2.0, < 4.0) jekyll-watch (~> 2.0) - kramdown (~> 2.3) + json (~> 2.6) + kramdown (~> 2.3, >= 2.3.1) kramdown-parser-gfm (~> 1.0) liquid (~> 4.0) - mercenary (~> 0.4.0) + mercenary (~> 0.3, >= 0.3.6) pathutil (~> 0.9) - rouge (~> 3.0) + rouge (>= 3.0, < 5.0) safe_yaml (~> 1.0) - terminal-table (~> 2.0) - jekyll-feed (0.15.1) + terminal-table (>= 1.8, < 4.0) + webrick (~> 1.7) + jekyll-feed (0.17.0) jekyll (>= 3.7, < 5.0) jekyll-gist (1.5.0) octokit (~> 4.2) jekyll-paginate (1.1.0) - jekyll-sass-converter (2.1.0) - sassc (> 2.0.1, < 3.0) - jekyll-seo-tag (2.7.1) + jekyll-sass-converter (3.1.0) + sass-embedded (~> 1.75) + jekyll-seo-tag (2.8.0) jekyll (>= 3.8, < 5.0) jekyll-sitemap (1.4.0) jekyll (>= 3.7, < 5.0) @@ -78,59 +99,177 @@ GEM jekyll-sitemap (~> 1.3) jekyll-watch (2.2.1) listen (~> 3.0) - kramdown (2.3.1) - rexml + json (2.19.3) + kramdown (2.5.2) + rexml (>= 3.4.4) kramdown-parser-gfm (1.1.0) kramdown (~> 2.0) - liquid (4.0.3) - listen (3.7.0) + liquid (4.0.4) + listen (3.10.0) + logger rb-fsevent (~> 0.10, >= 0.10.3) rb-inotify (~> 0.9, >= 0.9.10) + logger (1.7.0) mercenary (0.4.0) - multipart-post (2.1.1) - nokogiri (1.15.6-x86_64-darwin) - racc (~> 1.4) - nokogiri (1.15.6-x86_64-linux) - racc (~> 1.4) - nokogumbo (2.0.5) - nokogiri (~> 1.8, >= 1.8.4) - octokit (4.21.0) - faraday (>= 0.9) - sawyer (~> 0.8.0, >= 0.5.3) - parallel (1.21.0) + net-http (0.9.1) + uri (>= 0.11.1) + octokit (4.25.1) + faraday (>= 1, < 3) + sawyer (~> 0.9) pathutil (0.16.2) forwardable-extended (~> 2.6) - public_suffix (4.0.6) - racc (1.7.3) - rainbow (3.0.0) - rb-fsevent (0.11.0) - rb-inotify (0.10.1) + public_suffix (7.0.5) + rake (13.3.1) + rb-fsevent (0.11.2) + rb-inotify (0.11.1) ffi (~> 1.0) - rexml (3.3.6) - strscan - rouge (3.26.1) - ruby2_keywords (0.0.5) + rexml (3.4.4) + rouge (4.7.0) safe_yaml (1.0.5) - sassc (2.4.0) - ffi (~> 1.9) - sawyer (0.8.2) + sass-embedded (1.99.0) + google-protobuf (~> 4.31) + rake (>= 13) + sass-embedded (1.99.0-aarch64-linux-android) + google-protobuf (~> 4.31) + sass-embedded (1.99.0-aarch64-linux-gnu) + google-protobuf (~> 4.31) + sass-embedded (1.99.0-aarch64-linux-musl) + google-protobuf (~> 4.31) + sass-embedded (1.99.0-arm-linux-androideabi) + google-protobuf (~> 4.31) + sass-embedded (1.99.0-arm-linux-gnueabihf) + google-protobuf (~> 4.31) + sass-embedded (1.99.0-arm-linux-musleabihf) + google-protobuf (~> 4.31) + sass-embedded (1.99.0-arm64-darwin) + google-protobuf (~> 4.31) + sass-embedded (1.99.0-riscv64-linux-android) + google-protobuf (~> 4.31) + sass-embedded (1.99.0-riscv64-linux-gnu) + google-protobuf (~> 4.31) + sass-embedded (1.99.0-riscv64-linux-musl) + google-protobuf (~> 4.31) + sass-embedded (1.99.0-x86_64-darwin) + google-protobuf (~> 4.31) + sass-embedded (1.99.0-x86_64-linux-android) + google-protobuf (~> 4.31) + sass-embedded (1.99.0-x86_64-linux-gnu) + google-protobuf (~> 4.31) + sass-embedded (1.99.0-x86_64-linux-musl) + google-protobuf (~> 4.31) + sawyer (0.9.3) addressable (>= 2.3.5) - faraday (> 0.8, < 2.0) - strscan (3.1.0) - terminal-table (2.0.0) - unicode-display_width (~> 1.1, >= 1.1.1) - typhoeus (1.4.0) - ethon (>= 0.9.0) - unicode-display_width (1.8.0) - yell (2.2.2) + faraday (>= 0.17.3, < 3) + terminal-table (3.0.2) + unicode-display_width (>= 1.1.1, < 3) + unicode-display_width (2.6.0) + uri (1.1.1) + webrick (1.9.2) PLATFORMS - x86_64-darwin-19 - x86_64-linux + aarch64-linux-android + aarch64-linux-gnu + aarch64-linux-musl + arm-linux-androideabi + arm-linux-gnu + arm-linux-gnueabihf + arm-linux-musl + arm-linux-musleabihf + arm64-darwin + riscv64-linux-android + riscv64-linux-gnu + riscv64-linux-musl + ruby + x86-linux-gnu + x86-linux-musl + x86_64-darwin + x86_64-linux-android + x86_64-linux-gnu + x86_64-linux-musl DEPENDENCIES - html-proofer jekyll-theme-so-simple +CHECKSUMS + addressable (2.9.0) sha256=7fdf6ac3660f7f4e867a0838be3f6cf722ace541dd97767fa42bc6cfa980c7af + base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b + bigdecimal (4.1.1) sha256=1c09efab961da45203c8316b0cdaec0ff391dfadb952dd459584b63ebf8054ca + colorator (1.1.0) sha256=e2f85daf57af47d740db2a32191d1bdfb0f6503a0dfbc8327d0c9154d5ddfc38 + concurrent-ruby (1.3.6) sha256=6b56837e1e7e5292f9864f34b69c5a2cbc75c0cf5338f1ce9903d10fa762d5ab + csv (3.3.5) sha256=6e5134ac3383ef728b7f02725d9872934f523cb40b961479f69cf3afa6c8e73f + em-websocket (0.5.3) sha256=f56a92bde4e6cb879256d58ee31f124181f68f8887bd14d53d5d9a292758c6a8 + eventmachine (1.2.7) sha256=994016e42aa041477ba9cff45cbe50de2047f25dd418eba003e84f0d16560972 + faraday (2.14.1) sha256=a43cceedc1e39d188f4d2cdd360a8aaa6a11da0c407052e426ba8d3fb42ef61c + faraday-net_http (3.4.2) sha256=f147758260d3526939bf57ecf911682f94926a3666502e24c69992765875906c + ffi (1.17.4) sha256=bcd1642e06f0d16fc9e09ac6d49c3a7298b9789bcb58127302f934e437d60acf + ffi (1.17.4-aarch64-linux-gnu) sha256=b208f06f91ffd8f5e1193da3cae3d2ccfc27fc36fba577baf698d26d91c080df + ffi (1.17.4-aarch64-linux-musl) sha256=9286b7a615f2676245283aef0a0a3b475ae3aae2bb5448baace630bb77b91f39 + ffi (1.17.4-arm-linux-gnu) sha256=d6dbddf7cb77bf955411af5f187a65b8cd378cb003c15c05697f5feee1cb1564 + ffi (1.17.4-arm-linux-musl) sha256=9d4838ded0465bef6e2426935f6bcc93134b6616785a84ffd2a3d82bc3cf6f95 + ffi (1.17.4-arm64-darwin) sha256=19071aaf1419251b0a46852abf960e77330a3b334d13a4ab51d58b31a937001b + ffi (1.17.4-x86-linux-gnu) sha256=38e150df5f4ca555e25beca4090823ae09657bceded154e3c52f8631c1ed72cf + ffi (1.17.4-x86-linux-musl) sha256=fbeec0fc7c795bcf86f623bb18d31ea1820f7bd580e1703a3d3740d527437809 + ffi (1.17.4-x86_64-darwin) sha256=aa70390523cf3235096cf64962b709b4cfbd5c082a2cb2ae714eb0fe2ccda496 + ffi (1.17.4-x86_64-linux-gnu) sha256=9d3db14c2eae074b382fa9c083fe95aec6e0a1451da249eab096c34002bc752d + ffi (1.17.4-x86_64-linux-musl) sha256=3fdf9888483de005f8ef8d1cf2d3b20d86626af206cbf780f6a6a12439a9c49e + forwardable-extended (2.6.0) sha256=1bec948c469bbddfadeb3bd90eb8c85f6e627a412a3e852acfd7eaedbac3ec97 + google-protobuf (4.34.1) sha256=347181542b8d659c60f028fa3791c9cccce651a91ad27782dbc5c5e374796cdc + google-protobuf (4.34.1-aarch64-linux-gnu) sha256=f9c07607dc139c895f2792a7740fcd01cd94d4d7b0e0a939045b50d7999f0b1d + google-protobuf (4.34.1-aarch64-linux-musl) sha256=db58e5a4a492b43c6614486aea31b7fb86955b175d1d48f28ebf388f058d78a9 + google-protobuf (4.34.1-arm64-darwin) sha256=2745061f973119e6e7f3c81a0c77025d291a3caa6585a2cd24a25bbc7bedb267 + google-protobuf (4.34.1-x86-linux-gnu) sha256=b6da7891fe96b13038e5435d8ac8b8a84d78a468147a48a377fe8da40aba1c88 + google-protobuf (4.34.1-x86-linux-musl) sha256=ea0f453e78f4c30d0d9dbaa8cf9b33d2a1ea04ab2cad2c2a07e479411c05f1a9 + google-protobuf (4.34.1-x86_64-darwin) sha256=4dc498376e218871613589c4d872400d42ad9ae0c700bdb2606fe1c77a593075 + google-protobuf (4.34.1-x86_64-linux-gnu) sha256=87088c9fd8e47b5b40ca498fc1195add6149e941ff7e81c532a5b0b8876d4cc9 + google-protobuf (4.34.1-x86_64-linux-musl) sha256=8c0e91436fbe504ffc64f0bd621f2e69adbcce8ed2c58439d7a21117069cfdd7 + http_parser.rb (0.8.1) sha256=9ae8df145b39aa5398b2f90090d651c67bd8e2ebfe4507c966579f641e11097a + i18n (1.14.8) sha256=285778639134865c5e0f6269e0b818256017e8cde89993fdfcbfb64d088824a5 + jekyll (4.4.1) sha256=4c1144d857a5b2b80d45b8cf5138289579a9f8136aadfa6dd684b31fe2bc18c1 + jekyll-feed (0.17.0) sha256=689aab16c877949bb9e7a5c436de6278318a51ecb974792232fd94d8b3acfcc3 + jekyll-gist (1.5.0) sha256=495b6483552a3e2975a2752964ea7acddd545bc6e13ce2be15a50cec8d4c9f0f + jekyll-paginate (1.1.0) sha256=880aadf4b02529a93541d508c5cbb744f014cbfc071d0263a31f25ec9066eb64 + jekyll-sass-converter (3.1.0) sha256=83925d84f1d134410c11d0c6643b0093e82e3a3cf127e90757a85294a3862443 + jekyll-seo-tag (2.8.0) sha256=3f2ed1916d56f14ebfa38e24acde9b7c946df70cb183af2cb5f0598f21ae6818 + jekyll-sitemap (1.4.0) sha256=0de08c5debc185ea5a8f980e1025c7cd3f8e0c35c8b6ef592f15c46235cf4218 + jekyll-theme-so-simple (3.2.0) sha256=7b19157e9fea6398f3675fb32b6cd23fa149892d15e8d9d69586b9ac1da605c9 + jekyll-watch (2.2.1) sha256=bc44ed43f5e0a552836245a54dbff3ea7421ecc2856707e8a1ee203a8387a7e1 + json (2.19.3) sha256=289b0bb53052a1fa8c34ab33cc750b659ba14a5c45f3fcf4b18762dc67c78646 + kramdown (2.5.2) sha256=1ba542204c66b6f9111ff00dcc26075b95b220b07f2905d8261740c82f7f02fa + kramdown-parser-gfm (1.1.0) sha256=fb39745516427d2988543bf01fc4cf0ab1149476382393e0e9c48592f6581729 + liquid (4.0.4) sha256=4fcfebb1a045e47918388dbb7a0925e7c3893e58d2bd6c3b3c73ec17a2d8fdb3 + listen (3.10.0) sha256=c6e182db62143aeccc2e1960033bebe7445309c7272061979bb098d03760c9d2 + logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203 + mercenary (0.4.0) sha256=b25a1e4a59adca88665e08e24acf0af30da5b5d859f7d8f38fba52c28f405138 + net-http (0.9.1) sha256=25ba0b67c63e89df626ed8fac771d0ad24ad151a858af2cc8e6a716ca4336996 + octokit (4.25.1) sha256=c02092ee82dcdfe84db0e0ea630a70d32becc54245a4f0bacfd21c010df09b96 + pathutil (0.16.2) sha256=e43b74365631cab4f6d5e4228f812927efc9cb2c71e62976edcb252ee948d589 + public_suffix (7.0.5) sha256=1a8bb08f1bbea19228d3bed6e5ed908d1cb4f7c2726d18bd9cadf60bc676f623 + rake (13.3.1) sha256=8c9e89d09f66a26a01264e7e3480ec0607f0c497a861ef16063604b1b08eb19c + rb-fsevent (0.11.2) sha256=43900b972e7301d6570f64b850a5aa67833ee7d87b458ee92805d56b7318aefe + rb-inotify (0.11.1) sha256=a0a700441239b0ff18eb65e3866236cd78613d6b9f78fea1f9ac47a85e47be6e + rexml (3.4.4) sha256=19e0a2c3425dfbf2d4fc1189747bdb2f849b6c5e74180401b15734bc97b5d142 + rouge (4.7.0) sha256=dba5896715c0325c362e895460a6d350803dbf6427454f49a47500f3193ea739 + safe_yaml (1.0.5) sha256=a6ac2d64b7eb027bdeeca1851fe7e7af0d668e133e8a88066a0c6f7087d9f848 + sass-embedded (1.99.0) sha256=61942229dc7da4f335688196d43c1d3d5314060667a43ccf48f4b4c41b5578e1 + sass-embedded (1.99.0-aarch64-linux-android) sha256=3b077c8436424b45eb04edaa46514fc92cc333f17b3fcca45857d124d453cdf1 + sass-embedded (1.99.0-aarch64-linux-gnu) sha256=a46615b0295ca7bd979b9ce79f6b9f1d26881736400188bd6fd5c4b7c9b46473 + sass-embedded (1.99.0-aarch64-linux-musl) sha256=eaa6d56968909d1d54073c46e21c13fd5bbcb5af609d7e4fbe6b196426ca8e49 + sass-embedded (1.99.0-arm-linux-androideabi) sha256=9089a3aca8f16f855a2fc848c0762b09aef23251f91ec9714fea31c28c9094df + sass-embedded (1.99.0-arm-linux-gnueabihf) sha256=f5f0748934660cda6948917af6dc974caf4d36ea6121e450982153b7d9c49b55 + sass-embedded (1.99.0-arm-linux-musleabihf) sha256=29a4056e76bc136025ba5d03e82d86ecdabfb6c07a473a4fdedcd72fb28dbbc4 + sass-embedded (1.99.0-arm64-darwin) sha256=20773f2fb0e8f4d0194eb1874dab4c0ef60262ff6dafe29361e217beb2208629 + sass-embedded (1.99.0-riscv64-linux-android) sha256=7ac1145c066670d5918a7afae8445338c45b4d8e34ad2968bda7099665ba8d15 + sass-embedded (1.99.0-riscv64-linux-gnu) sha256=b8c421eba2e41fa3c94bffc971611d803aae336586a3baf2933c99e1c7548f88 + sass-embedded (1.99.0-riscv64-linux-musl) sha256=63b924eb97548bd1f31193c36fab89bb100cd1a9bd144789a9a596fc98244a09 + sass-embedded (1.99.0-x86_64-darwin) sha256=371774c83b6dce8a2cb7b5ce5a0f918ff2735bf200b00e3bc7067366654fff13 + sass-embedded (1.99.0-x86_64-linux-android) sha256=39c51b80c292fdb5157fee9166793374104c4e6639d77dfefc36c339aa5dce12 + sass-embedded (1.99.0-x86_64-linux-gnu) sha256=a4e2ae5e9951815cb8b3ab408cee8b800852491988a57de735f18d259c70d7c4 + sass-embedded (1.99.0-x86_64-linux-musl) sha256=94be72a6f856c610e67b12303dc76a58412e64b24ce97bdf4912199b8145c8dd + sawyer (0.9.3) sha256=0d0f19298408047037638639fe62f4794483fb04320269169bd41af2bdcf5e41 + terminal-table (3.0.2) sha256=f951b6af5f3e00203fb290a669e0a85c5dd5b051b3b023392ccfd67ba5abae91 + unicode-display_width (2.6.0) sha256=12279874bba6d5e4d2728cef814b19197dbb10d7a7837a869bab65da943b7f5a + uri (1.1.1) sha256=379fa58d27ffb1387eaada68c749d1426738bd0f654d812fcc07e7568f5c57c6 + webrick (1.9.2) sha256=beb4a15fc474defed24a3bda4ffd88a490d517c9e4e6118c3edce59e45864131 + BUNDLED WITH - 2.2.28 + 4.0.10 diff --git a/README.md b/README.md index bd46393..ac7aba0 100644 --- a/README.md +++ b/README.md @@ -49,14 +49,14 @@ On macOS you need to install brew, bundler.io, and Ruby version manager so that $ source ~/.zshrc ``` -1. Install the required Ruby version: +1. Install a currently supported Ruby version (example uses `3.2.2`): ``` - $ rbenv install 2.7.1 - $ rbenv global 2.7.1 + $ rbenv install 3.2.2 + $ rbenv global 3.2.2 $ rbenv version ``` - In return, you should see `ruby 2.7.1 2.7.1 (set by /Users/username/docslikecode/.ruby-version`. + In return, you should see output like `ruby 3.2.2 (set by /Users/username/docslikecode/.ruby-version)`. 1. Run `gem install bundle` to install the bundler gem, which helps with Ruby dependencies. 1. Run `bundle install` the first time you are in the `docslikecode` directory. diff --git a/_learn/000-docs-as-code-quick-start-guide.md b/_learn/000-docs-as-code-quick-start-guide.md new file mode 100644 index 0000000..c41a1a6 --- /dev/null +++ b/_learn/000-docs-as-code-quick-start-guide.md @@ -0,0 +1,248 @@ +--- +title: "Docs-as-Code Quick Start Guide" +layout: learn +image: + path: /images/learn/mikecogh-trains.jpg + thumbnail: /images/learn/github-logo400x200.png + caption: "Photo from [Flickr:mikecogh](https://flic.kr/p/pEn3RB)" +--- + +# Docs-as-Code Quick Start Guide + +**Build Your First Modern Documentation Workflow Using GitHub, Markdown, and Automation** + +--- + +## Introduction: Why Documentation Feels Broken + +If you’ve worked in documentation, you’ve probably experienced this: + +* Content lives in Word docs, wikis, or scattered tools +* Developers don’t contribute—or avoid docs entirely +* Publishing updates is slow and manual +* Documentation quickly becomes outdated + +The result? Frustration, inconsistency, and a constant feeling of playing catch-up. + +There’s a better way. + +--- + +## What Is Docs as Code? + +**Docs as Code** is an approach where you create and manage documentation using the same tools and workflows as software development. + +Instead of separate systems, you use: + +* Version control (Git) +* Plain text files (Markdown) +* Collaborative workflows (pull requests) +* Automated publishing (CI/CD) + +This brings documentation into the same ecosystem as your engineering team—making it faster, more collaborative, and more scalable. + +--- + +## What You Can Build with This Guide + +In the next 20–30 minutes, you’ll: + +* Create a documentation repository +* Write content in Markdown +* Make and review changes using pull requests +* Understand how publishing can be automated + +No advanced setup required—just a basic familiarity with Git concepts. + +--- + +## Step 1: Create a Repository + +Start by creating a new repository for your documentation, meaning a folder locally and a repository on a site like GitHub. + +Suggested name: + +``` +docs-example +``` + +This repository holds all your documentation files. + +### Why this matters + +Storing documentation in a repository gives you: + +* Version history +* Collaboration via pull requests +* A single source of truth + +--- + +## Step 2: Add Your First Markdown File + +Create a file called: + +``` +index.md +``` + +Add the following content: + +```markdown +# Welcome to Our Documentation + +This is our first docs-as-code project. + +## Getting Started + +This documentation is written in Markdown and managed in Git. +``` + +### Why Markdown? + +Markdown is: + +* Simple and readable +* Easy to edit +* Widely supported by documentation tools + +It removes formatting friction so you can focus on content. + +--- + +## Step 3: Make a Change Using a Pull Request + +Instead of editing directly on the main branch, create a new branch: + +``` +update-intro +``` + +Edit your file: + +```markdown +This documentation is written in Markdown and managed in Git. + +We use a docs-as-code workflow to collaborate and publish content. +``` + +Now open a pull request. + +### What’s happening here? + +You’ve just: + +* Proposed a change +* Made it visible for review +* Enabled collaboration + +This is the core of docs-as-code. + +--- + +## Step 4: Review and Collaborate + +In a real team, someone would: + +* Review your changes +* Leave comments +* Suggest improvements + +This creates: + +* Higher-quality documentation +* Shared ownership +* Better alignment with engineering + +--- + +## Step 5: Merge and Publish + +Once approved, merge the pull request. + +At this point, your documentation is: + +* Updated +* Versioned +* Ready to publish + +--- + +## Step 6: (Optional) Add a Static Site Generator + +To turn your Markdown into a website, you can use a static site generator like: + +* Jekyll +* Hugo +* Sphinx + +These tools: + +* Convert Markdown into HTML +* Apply themes and navigation +* Create a professional documentation site + +--- + +## Step 7: Automate Publishing + +The final step is automation. + +Using CI/CD, you can: + +* Automatically build your site +* Deploy it when changes are merged +* Keep documentation always up to date + +Now your workflow looks like this: + +**Write → Review → Merge → Publish (automatically)** + +--- + +## What You Just Achieved + +In a short time, you’ve: + +* Created a version-controlled documentation system +* Collaborated using pull requests +* Prepared content for automated publishing + +This is the foundation of docs as code. + +--- + +## Why This Changes Everything + +Compared to traditional documentation, this approach: + +* Reduces bottlenecks +* Improves collaboration with developers +* Enables faster updates +* Scales across teams and products + +Instead of being an afterthought, documentation becomes part of the development process. + +--- + +## What’s Next + +This quick start only scratches the surface. + +In the full book, you’ll learn how to: + +* Design scalable documentation architectures +* Choose the right tools and platforms +* Implement CI/CD pipelines for docs +* Manage large documentation sets across teams +* Build a sustainable docs-as-code culture + +--- + +## Ready to Go Further? + +If you found this useful, the full [book](https://docslikecode.com/book/) will take you from a simple workflow to a complete, production-ready documentation system. + +👉 Continue your journey with *Docs Like Code* + +--- diff --git a/_learn/07-evaluating-ssg-themes.md b/_learn/07-evaluating-ssg-themes.md index d6a5ba1..ec3e89f 100644 --- a/_learn/07-evaluating-ssg-themes.md +++ b/_learn/07-evaluating-ssg-themes.md @@ -6,11 +6,27 @@ image: thumbnail: /images/learn/ssg-themes400x225.png --- -Themes for static site generators often provide advanced user experience features such as navigation, search, and responsive designs for mobile consumption. You also analyze the theme to make decisions on the authoring side, such as a table format for large data tables. +Themes for static site generators (SSGs) often provide advanced user experience features such as navigation, search, and responsive designs for mobile consumption. You also analyze the theme to make decisions on the authoring side, such as a table format for large data tables. When researching and selecting a theme, analyze the possibilities for printed outputs, such as PDF or EPUB. Perhaps you need version control for both the output and the source files. The size of your site may mean you need to consider the performance gains you can make with the build. Themes are one part of this analysis. -Here's a short list of questions you may want to ask about the theme you use for a static site generator. +## Quick answer + +- **What this article covers:** Evaluating SSG themes for navigation, search, responsiveness, customization, localization, code blocks, images, tables, print output (PDF/EPUB), versioning, performance, and maintenance. +- **When to use this information:** Run this checklist when choosing, auditing, or customizing a theme before adoption. +- **Fast checklist with yes/no answers for evaluating SSG themes:** + - Clear navigation (sidebar, breadcrumbs, prev/next)? + - Search present, mobile-friendly, and configurable? + - Responsive UI for mobile (collapsible nav, readable TOC)? + - Easy branding/customization without heavy developer work? + - Rich code block features (syntax, copy, line numbers, highlighting)? + - Admonitions/notes supported and rendered properly? + - Images and captions behave on mobile and in print outputs? + - Tables render well in browsers and in PDF/EPUB sizes? + - Localization/translation support for UI labels? + - Theme updates manageable via version control and tracked versions? + +The rest of the article provides questions you can ask about the theme you use for a static site generator. ## Admonitions or notes Are there designs for output of levels of admonition, such as warning, information, and note? diff --git a/book/index.md b/book/index.md index 49138c5..6f2d6e2 100644 --- a/book/index.md +++ b/book/index.md @@ -2,11 +2,14 @@ layout: landing title: Get the Book excerpt: "Docs Like Code book in print and ebook. Paperback now available on Amazon, Barnes & Noble, Lulu, iBooks, and more. Learn about REST API docs, Swagger, OpenAPI, RAML, doc automation, templates, CI/CD for docs, GitHub Pages, reviews, and more." -last_modified_at: Sat May 13 08:43:14 CDT 2017 +last_modified_at: Mon Mar 30 20:11:21 CDT 2026 --- +# Learn Docs-as-Code from the Author Who Helped Define It -

Get Started with Docs as Code

+Transform how your team writes, manages, and publishes documentation using GitHub, Markdown, and automation. [Buy the book to learn how](#buy-the-book) + +👉 **Stop fighting outdated tools. Start building documentation like software.** Docs Like Code

We've transformed the way teams work together on docs, and we want to show you the best practices for writing docs using development tools and techniques. Now available in both print and ebook, check out Docs Like Code.

@@ -27,6 +30,114 @@ last_modified_at: Sat May 13 08:43:14 CDT 2017 background-color: #fff; color: #64baaa;"> Buy Now

+ +## What You’ll Learn + +- How to use Git and GitHub for documentation workflows +- Writing and structuring content in Markdown +- Collaborating with developers using pull requests +- Automating publishing with CI/CD +- Scaling documentation across teams and products + +## Why This Book Matters + +Most documentation teams struggle with: + +- Siloed tools and workflows +- Slow publishing cycles +- Poor collaboration with engineering +- Content that quickly becomes outdated + +**Docs Like Code shows you how to fix this.** + +By applying software development practices to documentation, you can: + +- Ship docs faster +- Improve accuracy and consistency +- Collaborate seamlessly with developers +- Build a sustainable, scalable documentation system + +--- + +## Who This Book Is For + +**This book is for:** +- Technical writers working with engineering teams +- Developer advocates and API documentation writers +- Teams adopting docs-as-code workflows +- Anyone using or evaluating GitHub for documentation + +**This book is not for:** +- Complete beginners with no exposure to Git or Markdown + +--- + +## What Experts Say + +> “A must-read for any technical writer looking to modernize their workflow.” + +> “Bridges the gap between writers and developers in a practical, actionable way.” + +> “One of the most useful resources on docs-as-code available today.” + +--- + +## About the Author + +Anne is a leader in developer documentation and the author of *Docs Like Code*. +She has worked extensively on API documentation, developer portals, and docs-as-code workflows across major technology organizations. + +--- + +## Preview the Book + +Want to see if it’s right for you? + +👉 Read the Quick Start Guide and explore the concepts before you buy. + +[Docs as Code Quick Start Guide](/learn/000-docs-as-code-quick-start-guide/) + +--- + +## Buy the Book + +Get your copy today: + +- Print and ebook editions available +- Ideal for individuals and teams + +👉 **Start improving your documentation workflow today** + +[Buy on Lulu](https://www.lulu.com/spotlight/justwriteclick) +[Buy on Amazon](https://amzn.to/4tiBLy6) + +--- + +## Frequently Asked Questions + +### What is docs as code? + +Docs as code is an approach where documentation is written, managed, and published using the same tools and workflows as software development (Git, Markdown, CI/CD). + +### Why use GitHub for documentation? + +GitHub enables version control, collaboration, and automation, making it easier to manage documentation at scale. + +### What tools are used in docs-as-code? + +Common tools include: +- Git and GitHub +- Markdown +- Static site generators (Jekyll, Hugo, Sphinx) +- CI/CD pipelines + +## Start Building Better Documentation + +If you’re ready to modernize your documentation workflow, this book will give you the foundation. + +👉 [Buy the Book on Amazon](https://amzn.to/4tiBLy6) + +

What's inside?

Why use GitHub for docs? If you're unsure of a good fit for your projects and teams, read about the potential wins with these techniques. Or, you may learn how to convince others who need to hear about the use cases.

@@ -54,68 +165,34 @@ last_modified_at: Sat May 13 08:43:14 CDT 2017 background-color: #fff; color: #fc5720;"> Buy Now

-

Who's using these techniques?

+> "The wonderful @annegentle introduced me to this a long while ago and Docs Like Code has been a huge improvement in /everything/. Check out https://docslikecode.com" +> +> Cody Bunch -> “I met with one of the devs today to go over a Pull Request that I had submitted with editorial comments, and in the course of conversation, I mentioned that I had not been working directly with developers for very long. +> If you haven’t read about it yet I’d recommend you to read — @annegentle #DocsLikeCode #software #product #Documentation #SaaS #tech #techcomm #technology #technicalwriting #techwriter #knowledgebase > -> He replied that he'd worked with technical editors in the past who were not very helpful, but that I was different. In fact, he assumed I was a developer at first because I was working in GitHub, effortlessly creating PRs!” ->
-> — _Kelly Holcomb, Senior Technical Editor, Oracle_ - -> “This book will be the go-to guide for people looking to get into the _Docs like Code_ world. It has been on my list to write for a while, and I'm glad someone did for me. :)” ->
-> — _Eric Holscher, Cofounder of Read the Docs and Write the Docs_ +> Sriram Hariharan -

Buy Now

- - - - - -

If you haven’t read about it yet I’d recommend you to read - @annegentle #DocsLikeCode” #software #product #Documentation #SaaS #tech #techcomm #technology #technicalwriting #techwriter #knowledgebase https://t.co/ferLQvgRPQ

— Sriram Hariharan (@Sri_AT72) February 14, 2018
- -

#docsLikeCode refers to the use of repos like #git for source/version control and doc generation. It facilitates #agile docs, in the same sprints as agile dev. Ref https://t.co/JUp8fQoGRs, cc @annegentle

— Mike Jang (@TheMikeJang) December 6, 2018
- - -

We do this for all documentation at @GDSTeam. The brilliant @annegentle has even written a book on 'docs as code' and has some ace case studies and guidance on her website https://t.co/AdPBAdRr7H. It works so well!

— Jen Lambourne (@Jenny__Anne) February 26, 2019
- - -

"Docs as Code" is the search term you're looking for! #lca2019 #techcomm #docsascode

— Lana (@Loquacities) January 21, 2019
-

Also, the wonderful @annegentle literally wrote the book on it :)

— Lana (@Loquacities) January 22, 2019
+> #docsLikeCode refers to the use of repos like #git for source/version control and doc generation. It facilitates #agile docs, in the same sprints as agile dev. +> +> Mike Jang +> We do this for all documentation at @GDSTeam. The brilliant @annegentle has written a book on 'docs as code' and has case studies and guidance on her website. It works so well! +> +> Jen Lambourne -

Just finished @annegentle's new book, Docs Like Code, and it's outstanding for devs. If you value quality docs, see https://t.co/pVbhOcB3Bx

— Carol Willing (@WillingCarol) March 1, 2017
- +> "Docs as Code" is the search term you're looking for! #lca2019 #techcomm #docsascode Also, the wonderful @annegentle literally wrote the book on it. +> +> Lana Brindley -

@annegentle My trick? Treating docs like code! 😉https://t.co/NuuTgJcs3M

— Carolyn Van Slyck (@carolynvs) March 12, 2017
- +> Just finished @annegentle's new book, Docs Like Code — outstanding for devs. If you value quality docs, see the book. +> +> Carol Willing -

Just finished "Docs Like Code" by @annegentle - Superb advice for modern technical writing. https://t.co/jI9jsA0OIy

— Doug Hellmann (@doughellmann) March 7, 2017
- +> Just finished "Docs Like Code" by @annegentle — Superb advice for modern technical writing. +> +> Doug Hellmann -

This one just moved to the top of my reading list. A book on how to treat docs like code by @annegentle. Awesome! > https://t.co/nRkSZkhv5x

— Patrick Andriessen (@napnamPat) March 6, 2017
- +> This one just moved to the top of my reading list: a book on how to treat docs like code by @annegentle. +> +> Patrick Andriessen diff --git a/index.html b/index.html index 3e1917b..239e615 100644 --- a/index.html +++ b/index.html @@ -1,60 +1,323 @@ --- layout: home -title: "Quick Start with Docs as Code" -excerpt: "Use Git and GitHub, static site generators, and CICD systems to write and automate documentation builds so you can focus on writing and organizing excellent content." +title: "Docs Like Code — Treat Your Documentation Like a Developer" +excerpt: "Learn to write, version, automate, and ship technical docs using the same tools developers use: Git, GitHub, static site generators, and CI/CD." search: false show_excerpts: true entries_layout: grid --- -
- - - - -
    -
  1. Create a GitHub account at github.com. Refer to GitHub Pro Account or GitHub Free Account for Technical Writing if you're wondering which pricing plan makes sense for you. Free is likely fine!
    2. -
  2. In your browser, create a repository with the same name as your GitHub username, followed by "github.io". - For example, my repository name is "annegentle.github.io".
    3. -
  3. On the repository's main page, on the Code tab, click Add file > Create new file. -

    GitHub Add file and Create file

    -
    4. -
  4. In the Name your file... field, enter "index.md" and under Edit new file, add a line or two of text that you want to publish as your new web landing page. -

    GitHub Edit new file

    5. -
  5. Add a message if you like, and click Commit new file. -

    GitHub Commit new file

    6. -
  6. Wait just a few seconds, then go to your new page, https://username.github.io. For an example, go to annegentle.github.io. -
  7. If you don't see a page, check the settings for GitHub Pages by going to the Settings tab for the repository, and then click Pages in the left-hand side. The Settings should look similar to these: -

    GitHub repository Settings then Pages sidebar

    8. -
  8. Go to pages.github.com for even more scenarios.

    That exercise gives you a taste of using GitHub as a content management system and publishing to a single web page automatically by pushing to a branch. Learn more by exploring the rest of this site.

    9. -
-
- -
-Learn more - -

Learn the tools

- -

Learn

- -

Learning GitHub or any system backed by `git` takes some time and practice. Try some lessons with multiple static site generators and deployment systems as well as how to test docs as code.

+ + + +
+
+

📘 Now in its Second Edition

+

Ship better docs by treating them like code

+

+ Version control, automation, and real team collaboration — the same workflow developers already use, applied to technical documentation. This site and the book behind it show you exactly how. +

+
+ Get the Book — Print or Ebook + What's inside? +
+

Available in print and ebook via Lulu · by Anne Gentle

+
+
+ + Docs Like Code book cover + +
+
+ + +
+

"This book will be the go-to guide for people looking to get into the Docs like Code world. It has been on my list to write for a while, and I'm glad someone did for me."

+

— Eric Holscher, Co-founder of Read the Docs & Write the Docs

-
+ +
+
+

Version every change

+

Use Git to track who changed what and why — for docs, not just code.

+
+
+

Automate your builds

+

CI/CD pipelines that publish your docs on every merge, no manual steps.

+
+
+

Review with pull requests

+

Writers and developers collaborate in the same workflow they already know.

+
+
+

Scale with your team

+

Patterns that work whether you're a solo writer or a distributed doc team.

+
+
- Docs Like Code Book + +
+

Who this is for

+
+
+ Technical Writers + Work alongside engineers without losing control of your docs. +
+
+ Developer Advocates + Publish and maintain API docs that stay in sync with the code. +
+
+ Engineering Teams + Adopt a lightweight docs workflow that fits your existing CI/CD setup. +
+
+ Doc Team Leads + Build systems that don't break when headcount or tooling changes. +
+
+
+ + +
+ What's new in the Second Edition? + Updated coverage of modern static site generators, expanded CI/CD automation examples, new case studies from teams at Sysdig, platformOS, and Redis, plus a deeper look at REST API documentation and OpenAPI workflows. + See full table of contents → +
-

Buy the book

+ +
+

Try it in your browser — under 10 minutes

+

No local setup needed. All you need is a GitHub account.

-

Buy

+
+ + Learn more about docs as code + -

We've transformed the way teams work together on docs, and we want to talk about the best practices for writing docs using development tools and techniques. Now in its second edition.

+
    +
  1. + Create a free GitHub account at github.com. + (Free vs Pro — which plan?) +
    2. +
  2. + Create a new repository named yourusername.github.io — for example, annegentle.github.io. +
    3. +
  3. + On the repository's Code tab, click Add file → Create new file. + GitHub Add file and Create file +
    4. +
  4. + Name the file index.md and add a line of text — this becomes your live web page. + GitHub Edit new file +
    5. +
  5. + Click Commit new file. + GitHub Commit new file +
    6. +
  6. + Wait a few seconds, then visit https://yourusername.github.io. + See annegentle.github.io for a live example. +

    + Don't see a page? Go to Settings → Pages in your repo and verify GitHub Pages is enabled. + GitHub Pages settings +
    + More scenarios at pages.github.com. +
    7. +
+ +

That's the core loop: write a file, commit it, and it publishes automatically. The book and guides on this site show you how to take that same idea much further.

+
-
-

Read the articles

-

Read more articles on this site about -using GitHub for documentation. Let's find out the best practices and create a balance point between artisanal craft and automation efficiency. -

+ +
+ 📚 Lessons & exercises → + 📰 Articles & case studies → + 🛒 Buy the book →