4 ms·

The article is both a why-doc and a how-doc. I do agree that this is a useful distinction. I'd have called how-docs and FYIs "howto", as I think that term wou

The article is both a why-doc and a how-doc. I do agree that this is a useful distinction. I'd have called how-docs and FYIs "howto", as I think that term would be recognised more clearly, but that's a quibble.

ebiester 8y ago
Internal documentation has a handful of patterns. There's the cookbook patern, which corresponds to a "how-to." There's the "readme" pattern, which is meant to conceptually get you started on a project. There's the "architecture" pattern, which is a conceptual design and talks about the rejected alternatives - this is not used everywhere but is a key deliverable in both outsourced and waterfall applications. There is the "small chunk of information that is hard to organize" pattern that has multiple solutions, be it FAQs or Etsy's bot. Immutable documentation, at its essence, isn't new. Wikis are in many ways immutable documentation due to the diff. The interesting thing here is trying to organize the "small bits of hard to organize" information around slack. More often, however, the real problem is that we need to properly organize this documentation at the point the organization becomes more evident. For a tool, that should be obvious: --help should be obvious. It's not true in all cases.
- lazyasciiart 8y ago
  > Internal documentation has a handful of patterns. This is a great way to articulate something I've been trying to talk to people about for a while - is this something you've thought of for yourself, or do you know of anywhere that talks about these patterns?
  - mr_tristan 8y ago
    I've noticed the concept of _information architecture_ is being used in technical communication more frequently these days, borrowed from graphic design. Which covers a bit more ground then patterns, including topics like search, labeling, and taxonomy. Sure, getting everyone to maintain docs with their features is useful. But given enough time, you'll end up with so many "close but not really close" concepts in documents it's very hard to stay on top of without someone putting some organization into play.
    - ebiester 8y ago
      Old school tech departments used to have librarians for documentation. I still think it would be valuable for departments, but it's one of those positions for which it is hard to quantify until you get much larger as an organization.
  - ebiester 8y ago
    I have some associated notes I've been thinking about for this. I haven't seen anyone articulate it, and I vaguely have an idea for a startup based on an opinionated guide to documentation, so I've held off on publishing until I know I'm ready to release it into the wild.

ebiester 8y ago

Internal documentation has a handful of patterns. There's the cookbook patern, which corresponds to a "how-to." There's the "readme" pattern, which is meant to conceptually get you started on a project. There's the "architecture" pattern, which is a conceptual design and talks about the rejected alternatives - this is not used everywhere but is a key deliverable in both outsourced and waterfall applications. There is the "small chunk of information that is hard to organize" pattern that has multiple solutions, be it FAQs or Etsy's bot. Immutable documentation, at its essence, isn't new. Wikis are in many ways immutable documentation due to the diff. The interesting thing here is trying to organize the "small bits of hard to organize" information around slack. More often, however, the real problem is that we need to properly organize this documentation at the point the organization becomes more evident. For a tool, that should be obvious: --help should be obvious. It's not true in all cases.

lazyasciiart 8y ago
> Internal documentation has a handful of patterns. This is a great way to articulate something I've been trying to talk to people about for a while - is this something you've thought of for yourself, or do you know of anywhere that talks about these patterns?
- mr_tristan 8y ago
  I've noticed the concept of _information architecture_ is being used in technical communication more frequently these days, borrowed from graphic design. Which covers a bit more ground then patterns, including topics like search, labeling, and taxonomy. Sure, getting everyone to maintain docs with their features is useful. But given enough time, you'll end up with so many "close but not really close" concepts in documents it's very hard to stay on top of without someone putting some organization into play.
  - ebiester 8y ago
    Old school tech departments used to have librarians for documentation. I still think it would be valuable for departments, but it's one of those positions for which it is hard to quantify until you get much larger as an organization.
- ebiester 8y ago
  I have some associated notes I've been thinking about for this. I haven't seen anyone articulate it, and I vaguely have an idea for a startup based on an opinionated guide to documentation, so I've held off on publishing until I know I'm ready to release it into the wild.