documentation   104667

« earlier    

Etsy’s experiment with immutable documentation - Code as Craft
Etsy has recognized that technical documentation is a mixture of two distinct types: a narrative that explains why a system exists (“why-docs”), and operational details that describe how to use the system (“how-docs”). In trying to overcome the problem of staleness, the crucial observation is that how-docs typically change faster than why-docs do. Therefore the more how-docs are mixed in with why-docs in a doc page, the more likely the page is to go stale.

We’ve leveraged this observation by creating an entirely separate system to hold our how-docs. The FYI system simply allows us to save Slack messages to a persistent data store. When someone posts a useful bit of documentation in a Slack channel, we tag it with the :fyi: reacji to save it as a how-doc. We then search our how-docs directly from Slack using a bot command called ?how.

FYIs are immutable: to update them, we simply add another FYI that is more timely and correct. Since FYIs don’t need to contain narrative, they’re easy to add, and easy to update. The ?how command always returns more recent FYIs first, so fresher matches always have higher priority. In this way, the FYI system combats documentation staleness by trading completeness for freshness.

We believe the separation of operational details from contextual narrative is a useful idea that can be used for documenting all kinds of systems. We’d love to hear how you feel about it! And we’re excited to hear about what tooling you’ve built to make documentation better in your organization. Please get in touch and share what you’ve learned. Documentation is hard! Let’s make it better!
documentation  etsy  code 
yesterday by piotch
Freebie: “Scribbler” Website Template (HTML, Sketch)
A responsive HTML template for coding projects with a clean, user friendly design. Crafted with the latest web technologies, the template is suitable for landing pages and documentations.

A responsive HTML template for coding projects with a clean, user friendly design. Crafted with the latest web technologies, the template is suitable for landing pages and documentations.

css  template  html  design  boilerplate  navigation  ux  ui  menu  documentation 
yesterday by michaelfox

« earlier    

related tags

1st  2018  2nd  administration  advice  angularjs  animation  api  appboy  art  association  aws-sdk-java  aws-sdk  aws  bash  battlestationsetup  beaglebone  best-practice  best_practices  bestpractice  bestpractices  blogs  boilerplate  book  books  bot  branches  brand  braze  building  california  changelog  charlesvenable  chatbot  cheatsheets  chef  city  cli  cms  code  collaboration  commemoration  communication  companies  configuration  corporate  css  cuisine  dash  data  datalog  datascript  day  design  deutsch  dev  developer  development  devops  docker  docs  domain  editor  education  eeprom  elm  engineering  entertainment  etsy  every  example  experience  facebook  femmes  ffdn  food  for-adafruit  foss  ganeti  generic  genre  gentrification  german  git  github  globenetselection  godoc  golang  gouvernement  graphs  grenode  guide  haml  handbook  hardware  how-the-big-dogs-do-it  howto  html  image  images  immutability  impression  index  information  instagram  install  installation  institutions  interface  internals  java  javadoc  javascript  jbdatko  jdk  jira  js  json  juri  jvm  knowledgebase  lang:en  lang:fr  learn  led  library  lighting  links  linux  local  logic  macos  manpage  manual  marketing  markup  matplotlib  meals  menu  mobile  mongodb  museum  navigation  node.js  node  not-sure-about-this  npm  official  online  opensource  oracle  packagemanager  participation  photography  podemo  policy  politique  postwar  process  processing  productivity  programming  programming_languages  projection  prosumerism  proxmox  public  python  quality  quebec  racket  react  read-later  read  readme  recreation  reference  remotes  rest-api  sante  sass  sculpture  sdk  security  server  service  sharing  slack.tweet  slack  socialmedia  software  space  stackoverflow  standards  static  streams  style-guides  subsystem  technical-writing  template  testing  todo  tool  tools  travail  tribal  tutorial  type-theory  ui  update  usability  ux  ve  version  versioning  violence  virtualization  warelogging  webdev  wiki  window-managers  windows-10  windows  with  wordpress  work  working  wsl  xcode  xmonad 

Copy this bookmark: