[HN Gopher] Unified theory of documentation systems
___________________________________________________________________
Unified theory of documentation systems
Author : O__________O
Score : 90 points
Date : 2022-06-25 11:47 UTC (11 hours ago)
(HTM) web link (documentation.divio.com)
(TXT) w3m dump (documentation.divio.com)
| uudecoded wrote:
| I don't understand what is going on here - I read this before on
| https://diataxis.fr - so I guess this is some sort of fork:
|
| 2021-04-07: https://github.com/evildmp/diataxis-documentation-
| framework/... Add license CC-BY-SA 4.0
|
| 2021-04-30: https://github.com/divio/diataxis-documentation-
| framework/co... Copyright change from Danielle Procida to Divio
|
| edit: fixed link
| kaycebasques wrote:
| I think Procida initially created this as part of their work
| with Divio and then forked it to the Diataxis site. The Divio
| site was definitely around before Diataxis and the Divio site
| was where these ideas originally gained a lot of popularity.
| O__________O wrote:
| They're officially related. Personally, prefer the link I used
| since it provides a table of contents and link to this YouTube
| presentation on the system:
|
| https://m.youtube.com/watch?v=t4vKPhjcMZg
| mjw1007 wrote:
| This variant seems worse than the dataxis one.
|
| It's already a weakness of this "theory" that it leaves only
| the reference for documentation that's intended to be complete
| and correct, while also recommending that the reference be
| organised as a list of the available operations.
|
| But this divio variant goes so far as to say that, when writing
| the reference, "don't allow explanations of concepts".
|
| I believe good documentation often needs rigorous definitions
| of the concepts involved, not just a list of functions or
| configuration items or whatever.
|
| So either the reference should have space for those, or the
| explanation should be in a more rigorous style, not a "more
| relaxed" discussion.
| O__________O wrote:
| Prior related HN comments:
|
| https://hn.algolia.com/?q=https%3A%2F%2Fdiataxis.fr%2F
|
| https://hn.algolia.com/?query=Four%20kinds%20of%20documentat...
|
| https://hn.algolia.com/?q=https%3A%2F%2Fdocumentation.divio....
| twobitshifter wrote:
| I just followed the links, but this seems to have left out
| specifications.
| jimmySixDOF wrote:
| I agree these don't fit into the 4Ds because the spec is many
| times the contractual document used for handover compliance
| line item by line item as part of a larger RFP. Much of it
| should end up in permanent operational documents but you keep
| the baseline fixed (with amendments) to compare the original
| intent against what you end up with. Still, I'm not sure this
| matters enough to add another D to the taxonomy. If I was to
| add one it would be D for Diagrams which matter enough to be a
| category of their own ;}
| O__________O wrote:
| Interesting point. Generally, in my experience, specifications,
| that is the documents produced prior to building a system are
| replaced by the documentation that's created after the system
| is built.
|
| I have seen some projects try to keep the specs updated, even
| fewer that try to keep the specs/build/docs in sync via tagging
| and unique IDs.
|
| If the specs were within this framework, my guess is they would
| go under reference; for example, an API spec would easily be
| kept in sync and would naturally go under the reference
| section. In fact, the example given is for a CLI:
|
| https://docs.divio.com/en/latest/reference/divio-cli/
| hyperpape wrote:
| I read this a long time ago, and I'm probably not reading it
| again today, but I remember finding Hillel Wayne's comment apt---
| there really are more dimensions than this.
| https://twitter.com/hillelogram/status/1438972753957294080?s...
| ChrisMarshallNY wrote:
| This looks quite interesting. I had not heard of it, before.
|
| At first blush, it seems to make sense. I'll review it, in my
| copious free time...
| daxfohl wrote:
| There's also a separate dimension for consuming vs developing.
| Probably this sits under the category of "too obvious to point
| out". But still, in large orgs I frequently see wikis that have
| stuff meant for team members and stuff meant for consumers of the
| service, with no clear separation.
| [deleted]
___________________________________________________________________
(page generated 2022-06-25 23:01 UTC)