3 ms·

Summary: HIGH Documentation = HIGH staleness + HIGH loss. HIGH staleness is because nobody wants to do it (status is lower). Also… nobody else can do it (full u

Summary: HIGH Documentation = HIGH staleness + HIGH loss. HIGH staleness is because nobody wants to do it (status is lower). Also… nobody else can do it (full understanding of what is being documented is needed) So, to solve the first staleness part, there is only two ways: raise the documenter status, or make it somewhat possible (easier?) for someone else to do at least a part of it. are they both really that hopeless? PS: to solve the second loss/discovery part, I think we are heading for that AI powered simple "unified search" experience.

euroderf 4y ago
A feature of docs-as-code is having the (typ. markdown) docs live in the code directories. Leaving no excuses for tech people not to update them, or at least insert a TODO. Another idea might be, whenever a new feature is closed out, auto-allocate some percentage of its implementation time to documentation, and schedule an interview with a tech writer.
beckingz 4y ago
AI can't solve search. If you look at how google did it, they bullied and cajoled site owners to add detailed metadata to the top of pages. It's not magic, it's creating incentives for people to create documentation.
- CrypticShift 4y ago
  First, I’m assuming the documentation is already updated (i.e., 1st part is OK = no staleness) Second, the whole point of AI NLP search (i.e., 2nd part = loss) is that it does not need metadata (which was the basis of the now mostly abandoned semantic web approach to KM).
- mycall 4y ago
  The better question to ask is if AI can do the ghost writing that high-documentation culture needs. This is an interesting hypothesis for GPT-4
- spencerchubb 4y ago
  'bullied and cajoled' is an interesting set of verbs to use here. Is there a reason not to use metadata? Doesn't it make the web easier to index, and therefore easier for everyone to use?
  - midoridensha 4y ago
    >Is there a reason not to use metadata? Doesn't it make the web easier to index, and therefore easier for everyone to use? Yes, there's a very good reason not to use metadata: it's extra work, and it's not very fun, just like writing docs for software. So people don't want to do it because it isn't "sexy" (and there aren't very good incentives to overcome people's reluctance to do that work). Because of this, just like any job that people don't really want to do, you have to "bully and cajole" them into doing it.
  - thepawn1 4y ago
    The age old issue. There's oodles of data at how people don't keep doing it because it's toil to them.
  - beckingz 4y ago
    A human has to write this type of metadata. If you don't include the right metadata, google won't rank you highly. If you include the right metadata, your content will get higher rankings and the snazzy preview cards on different social media platforms. Metadata is good! There are structural incentives to be mediocre though.
bloaf 4y ago
You need to 1) Link to the documentation in your tools 2) Ensure everyone has edit access to the linked documents

euroderf 4y ago

A feature of docs-as-code is having the (typ. markdown) docs live in the code directories. Leaving no excuses for tech people not to update them, or at least insert a TODO. Another idea might be, whenever a new feature is closed out, auto-allocate some percentage of its implementation time to documentation, and schedule an interview with a tech writer.

beckingz 4y ago

AI can't solve search. If you look at how google did it, they bullied and cajoled site owners to add detailed metadata to the top of pages. It's not magic, it's creating incentives for people to create documentation.

CrypticShift 4y ago
First, I’m assuming the documentation is already updated (i.e., 1st part is OK = no staleness) Second, the whole point of AI NLP search (i.e., 2nd part = loss) is that it does not need metadata (which was the basis of the now mostly abandoned semantic web approach to KM).
mycall 4y ago
The better question to ask is if AI can do the ghost writing that high-documentation culture needs. This is an interesting hypothesis for GPT-4
spencerchubb 4y ago
'bullied and cajoled' is an interesting set of verbs to use here. Is there a reason not to use metadata? Doesn't it make the web easier to index, and therefore easier for everyone to use?
- midoridensha 4y ago
  >Is there a reason not to use metadata? Doesn't it make the web easier to index, and therefore easier for everyone to use? Yes, there's a very good reason not to use metadata: it's extra work, and it's not very fun, just like writing docs for software. So people don't want to do it because it isn't "sexy" (and there aren't very good incentives to overcome people's reluctance to do that work). Because of this, just like any job that people don't really want to do, you have to "bully and cajole" them into doing it.
- thepawn1 4y ago
  The age old issue. There's oodles of data at how people don't keep doing it because it's toil to them.
- beckingz 4y ago
  A human has to write this type of metadata. If you don't include the right metadata, google won't rank you highly. If you include the right metadata, your content will get higher rankings and the snazzy preview cards on different social media platforms. Metadata is good! There are structural incentives to be mediocre though.

bloaf 4y ago

You need to 1) Link to the documentation in your tools 2) Ensure everyone has edit access to the linked documents