4 ms·

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

by 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

by polote 5y ago

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