5 ms·

The challenge is that there are two directions for the knowledge retrieval: top-down and bottom-up. The "problem" here is that failure to learn from past, well-

The challenge is that there are two directions for the knowledge retrieval: top-down and bottom-up. The "problem" here is that failure to learn from past, well-characterized solutions means we will be forced to revisit problems experimentally (expensive) that could be solved by examining the documentation (relatively cheap). Literate programming and inline documentation is great for understanding the bottom-up picture, because you colocate the components that are needed for understanding. For top-down, you are often summarizing several projects or proposals and trying to explain trajectory and architecture, and necessarily will not always have an obvious "best" location for retrieval. For example, consider an assembly line in a factory. Having work instructions and debugging manuals next to a station is great, but where should we place the information explaining why this station must be configured in particular way to prevent an issue six steps downstream? Do both stations now need to have that information documented? Do we have higher-level documentation that needs to be synchronized? How would we find information about the changes made while debugging that process which ultimately did not make the cut, but would be useful to know as negative experiments? I would be curious to learn more about the tool you work on. I have never found a good solution for architecting layered information for retrievablility, only least-worst hacks.

polote 5y ago
Yes, having documentation close to source code is bottom-up and being able to index this documentation somewhere is the top-down. Some documentation are useful to have in both ways and some are not. But if you force people to use a new tool to store their documentation, some will stop documenting and some will start, the best solution is to allow both ways but to index it in a central place without having to duplicate information. > I have never found a good solution for architecting layered information for retrievablility, only least-worst hacks. I don't know if we will end up in a 'good solution' situation, as that's quite a complex topic, but we try to approach the problem with different ideas in mind : - A great user experience, how to encourage people to document and search in the documentation (I always joke that, a documentation platform is good only when all salespeople of a company use it everyday) - Spreading the ownership of content organization, how we can rely on 1-2% of employees having 'expert' responsibilities to create the right framework to collaborate in his group - Letting anyone curate information even on content they are not responsible of. As people that like documenting or care about it are not the same than the ones having expert knowledge on the topic. At the end it's always difficult to discuss theory on those kind of topics as the only thing that counts is that it works in practice. And that's also why tools are important, they are able to hide the theory and let users use simple things
- monetus 5y ago
  Have you heard of pol.is or vtaiwan? Do you have opinions on them or of what they are trying to accomplish that you wouldn't mind sharing? There are others I'm having trouble remembering at the moment. Letting anyone curate information even on content they are not responsible of. As people that like documenting or care about it are not the same than the ones having expert knowledge on the topic. This is how a system should be for good faith contributors. It has the eternal wikipedia-style problem of truthiness always being in question though. In normal internal documentation, I don't imagine this being too much of a problem. It would be nice if good versions of these communication platforms, seemingly like dokkument, became available for more of the public at large.
  - polote 5y ago
    > Have you heard of pol.is or vtaiwan I never heard about them, pol.is is interesting, I will read about it. As for vtaiwan I don't think there are similar problem that we are trying to tackle. It feels like vtaiwan is more like a forum where people who are willing to contribute can contribute, in an organization one big challenge is to onboard people who don't care about collaborating. > It has the eternal wikipedia-style problem of truthiness Wikipedia is the reference when talking about curation and collaboration, and being able to have an internal Wikipedia (not just the tool, but also the contributors, the readers, the overall system) is the goal. In a company you can create an approval system with experts accepting new changes that fix the issue about truthiness. > It would be nice if good versions [...] became available for more of the public at large. That's my personal long term goal, whether it's good practice, searching for a flat, a good restaurant, ... there are ways that crowd-curation can solve a lot of the issue we have today, there was an interesting article about it a few days ago on HN : https://news.ycombinator.com/item?id=29130017 https://news.ycombinator.com/item?id=29130017

polote 5y ago

Yes, having documentation close to source code is bottom-up and being able to index this documentation somewhere is the top-down. Some documentation are useful to have in both ways and some are not. But if you force people to use a new tool to store their documentation, some will stop documenting and some will start, the best solution is to allow both ways but to index it in a central place without having to duplicate information. > I have never found a good solution for architecting layered information for retrievablility, only least-worst hacks. I don't know if we will end up in a 'good solution' situation, as that's quite a complex topic, but we try to approach the problem with different ideas in mind : - A great user experience, how to encourage people to document and search in the documentation (I always joke that, a documentation platform is good only when all salespeople of a company use it everyday) - Spreading the ownership of content organization, how we can rely on 1-2% of employees having 'expert' responsibilities to create the right framework to collaborate in his group - Letting anyone curate information even on content they are not responsible of. As people that like documenting or care about it are not the same than the ones having expert knowledge on the topic. At the end it's always difficult to discuss theory on those kind of topics as the only thing that counts is that it works in practice. And that's also why tools are important, they are able to hide the theory and let users use simple things

monetus 5y ago
Have you heard of pol.is or vtaiwan? Do you have opinions on them or of what they are trying to accomplish that you wouldn't mind sharing? There are others I'm having trouble remembering at the moment. Letting anyone curate information even on content they are not responsible of. As people that like documenting or care about it are not the same than the ones having expert knowledge on the topic. This is how a system should be for good faith contributors. It has the eternal wikipedia-style problem of truthiness always being in question though. In normal internal documentation, I don't imagine this being too much of a problem. It would be nice if good versions of these communication platforms, seemingly like dokkument, became available for more of the public at large.
- polote 5y ago
  > Have you heard of pol.is or vtaiwan I never heard about them, pol.is is interesting, I will read about it. As for vtaiwan I don't think there are similar problem that we are trying to tackle. It feels like vtaiwan is more like a forum where people who are willing to contribute can contribute, in an organization one big challenge is to onboard people who don't care about collaborating. > It has the eternal wikipedia-style problem of truthiness Wikipedia is the reference when talking about curation and collaboration, and being able to have an internal Wikipedia (not just the tool, but also the contributors, the readers, the overall system) is the goal. In a company you can create an approval system with experts accepting new changes that fix the issue about truthiness. > It would be nice if good versions [...] became available for more of the public at large. That's my personal long term goal, whether it's good practice, searching for a flat, a good restaurant, ... there are ways that crowd-curation can solve a lot of the issue we have today, there was an interesting article about it a few days ago on HN : https://news.ycombinator.com/item?id=29130017 https://news.ycombinator.com/item?id=29130017