5 ms·

I’ve been involved with technical documentation a lot by now, and think the only actually working solution for archiving and passing on knowledge is something l

by 9dev 3y ago

I’ve been involved with technical documentation a lot by now, and think the only actually working solution for archiving and passing on knowledge is something like a Wiki, combined with something like GitHub discussions, where individual discussions can lead to change requests or new articles. That way, discussions of the topic could lead to changes on the canon.

csydas 3y ago
I do agree with the idea of wiki is the right way, but I think most orgs overestimate to an extreme degree how much work a "simple wiki" (my words) really takes to be useful. One of the disadvantages of a mailing list that is actually a surprise feature is the lack of content curation; as pedantic as the wikipedia edit wars might be, having tried to maintain a wiki for one of my work places, I understand why they happen, even when you have a well documented and followed structure and content guideline that everyone is aware of. Generating consistent and accurate content, and curating said content, is really a full time job, and for technical content neither item is something I'm comfortable sourcing to a group that isn't also able to contribute to content on their own in a meaningful way, as this can really harm the value of such a wiki. I think the tooling is less important than the dedication to developing a structure, enforcing the structure, and curating what gets into the documentation very hard. Mailing lists kind of avoid this because they neither propose to be curated no require someone to decide "today I will write X and Y articles", the interest and the discussions define the direction of the content creation. Great for getting data out there, but not great at being searchable or meeting user needs for relevance.
- hutzlibu 3y ago
  The main work with wikis, is keeping them up to date. Worse than no documentation is wrong documentation in my experience. So if there is a vibrant community, than solid ressources like the Arch Wiki can get created and maintained ( but even there I encountered out dated, or wrong information).
  - 6510 3y ago
    I've pondered how one could set up conditions in documentation. For example display [collapsed] code in the document that implements the functionality there described. If the exact code is no longer found in the source the article or section gets a warning banner, a [collapsed] div view and the wiki bug tracker displaying the issue. Perhaps one could also programmatically generate a list of missing articles by looking at code and implementations.
  - midasuni 3y ago
    I Try very hard to explain why we don’t document facts on our wiki, but concepts, with links to facts. We aim to maintain a single source of truth of what should be, and have automated systems to tell us what is. Want to know what ip server “lon-rds14” should be? Ping it. DNS is driven from the ip mgmt tool, job done. Check the auto populated cmdb which will tell you the current interfaces on a given host to tell you what ip it really is. Want to know where on the network it is? Search the portmapper, which tells you (through switch labels) where the host should be, and through mac/ip/dns where is actually is (cmdb also has the lldp entry - duplicating data that automatically updated is fine) On our work wiki (20k users), different departments copy and paste information from one page to another so it’s in “their” area. Even worse one department locks down its area so it’s hidden to those outside the department!
- 9dev 3y ago
  To be clear, a Wiki as it is isn’t the best possible tool to gather knowledge about a specific topic in general, even if it works for the Wikipedia. Kind of like how git isn’t perfect for projects other than the Linux kernel. I agree that dedication is vastly more important than tooling, but simultaneously you need a medium that is both simple to use and suited to preserve and accumulate knowledge; somewhat of a middleground between a long PDF document and a Slack channel with 10k messages. At this point, I’m pretty sure it must be easy to get new topics out there, then hone them step by step into something useful for the future.

by 9dev 3y ago

csydas 3y ago

I do agree with the idea of wiki is the right way, but I think most orgs overestimate to an extreme degree how much work a "simple wiki" (my words) really takes to be useful. One of the disadvantages of a mailing list that is actually a surprise feature is the lack of content curation; as pedantic as the wikipedia edit wars might be, having tried to maintain a wiki for one of my work places, I understand why they happen, even when you have a well documented and followed structure and content guideline that everyone is aware of. Generating consistent and accurate content, and curating said content, is really a full time job, and for technical content neither item is something I'm comfortable sourcing to a group that isn't also able to contribute to content on their own in a meaningful way, as this can really harm the value of such a wiki. I think the tooling is less important than the dedication to developing a structure, enforcing the structure, and curating what gets into the documentation very hard. Mailing lists kind of avoid this because they neither propose to be curated no require someone to decide "today I will write X and Y articles", the interest and the discussions define the direction of the content creation. Great for getting data out there, but not great at being searchable or meeting user needs for relevance.

hutzlibu 3y ago
The main work with wikis, is keeping them up to date. Worse than no documentation is wrong documentation in my experience. So if there is a vibrant community, than solid ressources like the Arch Wiki can get created and maintained ( but even there I encountered out dated, or wrong information).
- 6510 3y ago
  I've pondered how one could set up conditions in documentation. For example display [collapsed] code in the document that implements the functionality there described. If the exact code is no longer found in the source the article or section gets a warning banner, a [collapsed] div view and the wiki bug tracker displaying the issue. Perhaps one could also programmatically generate a list of missing articles by looking at code and implementations.
- midasuni 3y ago
  I Try very hard to explain why we don’t document facts on our wiki, but concepts, with links to facts. We aim to maintain a single source of truth of what should be, and have automated systems to tell us what is. Want to know what ip server “lon-rds14” should be? Ping it. DNS is driven from the ip mgmt tool, job done. Check the auto populated cmdb which will tell you the current interfaces on a given host to tell you what ip it really is. Want to know where on the network it is? Search the portmapper, which tells you (through switch labels) where the host should be, and through mac/ip/dns where is actually is (cmdb also has the lldp entry - duplicating data that automatically updated is fine) On our work wiki (20k users), different departments copy and paste information from one page to another so it’s in “their” area. Even worse one department locks down its area so it’s hidden to those outside the department!
9dev 3y ago
To be clear, a Wiki as it is isn’t the best possible tool to gather knowledge about a specific topic in general, even if it works for the Wikipedia. Kind of like how git isn’t perfect for projects other than the Linux kernel. I agree that dedication is vastly more important than tooling, but simultaneously you need a medium that is both simple to use and suited to preserve and accumulate knowledge; somewhat of a middleground between a long PDF document and a Slack channel with 10k messages. At this point, I’m pretty sure it must be easy to get new topics out there, then hone them step by step into something useful for the future.