5 ms·

So, how did you solve the organization problem? That has always been the biggest problem with confluence and wikis in general. People actively dislike confluen

So, how did you solve the organization problem? That has always been the biggest problem with confluence and wikis in general. People actively dislike confluence. (And it's something that's stuck in my craw - how do we build documentation that's easy to organize? That's my quarantine project. :)

matwood 6y ago
I've thought about this problem a lot and the conclusion I came to is that tools like Confluence are like the original Yahoo directory of links. Organizing seems like a good idea when there are a small number of items, but it quickly becomes unwieldy. What I've settled on, while not perfect, is shared Google docs where owners of the doc allow suggestions to help keep it up to date.
rglullis 6y ago
Confluence as a Knowledge System is like Democracy for Political systems: the worst ever, except for everything else that was tried. As much as I'd like to replace it, it did everything we needed and was better than any alternatives that we considered for both tech/non-tech teams. The solution we had was to give one Space for each team/department in the company: one space for Customer Support, one for Engineering, Data Scientists, Business Analysts and Operations/Management. Each team lead was responsible in ensuring that other teams from the company could find the information needed, but aside from that we let each team organize itself. The only hard rule was the one I stated above, everything else came somewhat organically. Managers and Business Analysts, for instance, still preferred to work in Word/Excel, so their pages was mostly just placeholders for Office Docs and attachments. This was fine by me, as long as they could always respond quickly with the right file/link if someone else in the team asked for something.
- AsyncAwait 6y ago
  DokuWiki works miles better for me than Confluence ever did.
- ebiester 6y ago
  The biggest problem is that "everything else that was tried" wasn't from experts who truly understand information management, nor has our industry learned patterns from other industries that also have similar problems. I'm trying to do that work now. It's not even that I don't think it can be done in confluence or wikis in general, but rather we don't have a great methodology in organizing it. I'm keeping a list of what I find at https://www.ebiester.com/annotated-links/documentation/2020/05/04/annotated-documentation-links.html https://www.ebiester.com/annotated-links/documentation/2020/... but I'm not seeing what I really want just yet.
  - rglullis 6y ago
    I am afraid I won't be able to help you much there. Every place I saw trying to come up with a grand top-down scheme to organize documentation failed. Too much structure, and people will wait until they have all of the details needed to start contributing, or they will not contribute unless it's "their job". Too much flexibility and they don't know where to start. I found that it was always better to let documentation and knowledge sharing follow the same principles as code: let it come bottom-up, see what patterns emerge and only worry about structure when the current practices hit a bottleneck. But then again I never worked on any project that I had hundreds of people directly depending on the documentation, so it might not work as a strategy for larger-scale organizations.
- curryst 6y ago
  > The solution we had was to give one Space for each team/department in the company This is the single biggest tip I would give any company who uses Confluence. For some reason, most companies I work for that use Confluence insist on using minimal separation of Spaces. I.e. IT in general has a Space, and my team has a folder nested 6 folders deep in some path that I can never remember and have to bookmark. It makes search effectively useless. If I search for "X api documentation" I get 10,000 results ranging from meeting minutes that some unrelated team put up that just happen to use those terms, to pages from other teams documenting how they use the API. A Space should be treated the same as a Jira project. If I had my way, I would create a Space every time we created a Jira project. And my biggest request for the Confluence team would be better markdown support (I should be able to indicate that I want to type Markdown without having to click through a giant list), and a way to set up a space to sync from Markdown files stored in Git. Some of us don't want to use the WYSIWYG editor, and I would love to be able to use an MR review process for documentation changes before they go live.
  - rglullis 6y ago
    From Steve Yegge's famous Rant about Google not understanding platforms: So one day Jeff Bezos issued a mandate. He's doing that all the time, of course, and people scramble like ants being pounded with a rubber mallet whenever it happens. But on one occasion -- back around 2002 I think, plus or minus a year -- he issued a mandate that was so out there, so huge and eye-bulgingly ponderous, that it made all of his other mandates look like unsolicited peer bonuses. His Big Mandate went something along these lines: All teams will henceforth expose their data and functionality through service interfaces. Teams must communicate with each other through these interfaces. There will be no other form of interprocess communication allowed: no direct linking, no direct reads of another team's data store, no shared-memory model, no back-doors whatsoever. The only communication allowed is via service interface calls over the network. It doesn't matter what technology they use. HTTP, Corba, Pubsub, custom protocols -- doesn't matter. Bezos doesn't care. All service interfaces, without exception, must be designed from the ground up to be externalizable. That is to say, the team must plan and design to be able to expose the interface to developers in the outside world. No exceptions. Anyone who doesn't do this will be fired. Thank you; have a nice day! I think about that a lot when designing any system, machine- or human-centered, that needs to communicate with a disparate group of entities. Encapsulate the implementation details to those who are closest to the actual information and have enough power to take action, and make the contact interfaces very explicit. This alone will get you 85% of a functional system. The rest is just selecting actors in your system that know how to cooperate and understands these boundaries.
phixiuz 6y ago
Also have similar experience with Confluence, as an alternative: we adopted a VuePress static site that we host internally (behind proxy), which basically just renders a bunch of markdown files. For easy discoverability of content we use Algolia's documentation search on top of it. For updating content we either use git locally for technical people, non-technical people can also directly update the content on remote git via gitlab interface. This has been working really well for us once setup, the main challenge we still have now is how to effectively communicate changes to the relevant people at the most appropriate time. Your knowledge system keeping in sync with your version control is also a major plus, this is the primary reason why I don't like tools like Confluence, because it's easy for them to get out of sync with the actual system, and this can require too much coordination.
- rglullis 6y ago
  > it's easy for them to get out of sync with the actual system, and this can require too much coordination. I don't follow. How much do you have of your non-techies updating your knowledge base and how do they get to know if what they are updating is "in sync" with the system if the changes are making are orthogonal with the functionality? It seems your case is mostly about documentation of the technical product, specs, requirements. Yeah, this can go to your version control, and I would bet that you could find a Confluence plugin that would generate the documentation from version control and sync with the rest of your Confluence pages if you wanted. But I really, really doubt your method can scale beyond the IT side of any middle-to-large organization. The moment you ask Business/Customer Support people to actually go look at anything like Gitlab/Github's interface is the moment you lose 90% percent of buy-in from both non-techies and management at any company that is not absolutely dominated by Software Engineers. Requiring integration with version control is a convenience for engineers, but it is so far from the tooling from those that live on Excel sheets that you might as well ask them to never touch the documentation side.
  - phixiuz 6y ago
    Granted, we're still a fairly small organization (+- 10), but our business and customer support people are also using Gitlab to maintain our knowledge base: once you properly guide them on how to use it, they are definitely able to handle this. All the actual git operations happen under the hood of the web interface. So we do strongly believe this is scalable, at least for our use case. This has been working fine in fact for long-lived information across multiple departments (not only technical docs, but also e.g. sales/customer support guidelines). For short-lived information we use Google Docs (e.g. meeting summaries).

matwood 6y ago

I've thought about this problem a lot and the conclusion I came to is that tools like Confluence are like the original Yahoo directory of links. Organizing seems like a good idea when there are a small number of items, but it quickly becomes unwieldy. What I've settled on, while not perfect, is shared Google docs where owners of the doc allow suggestions to help keep it up to date.

rglullis 6y ago

Confluence as a Knowledge System is like Democracy for Political systems: the worst ever, except for everything else that was tried. As much as I'd like to replace it, it did everything we needed and was better than any alternatives that we considered for both tech/non-tech teams. The solution we had was to give one Space for each team/department in the company: one space for Customer Support, one for Engineering, Data Scientists, Business Analysts and Operations/Management. Each team lead was responsible in ensuring that other teams from the company could find the information needed, but aside from that we let each team organize itself. The only hard rule was the one I stated above, everything else came somewhat organically. Managers and Business Analysts, for instance, still preferred to work in Word/Excel, so their pages was mostly just placeholders for Office Docs and attachments. This was fine by me, as long as they could always respond quickly with the right file/link if someone else in the team asked for something.

AsyncAwait 6y ago
DokuWiki works miles better for me than Confluence ever did.
ebiester 6y ago
The biggest problem is that "everything else that was tried" wasn't from experts who truly understand information management, nor has our industry learned patterns from other industries that also have similar problems. I'm trying to do that work now. It's not even that I don't think it can be done in confluence or wikis in general, but rather we don't have a great methodology in organizing it. I'm keeping a list of what I find at https://www.ebiester.com/annotated-links/documentation/2020/05/04/annotated-documentation-links.html https://www.ebiester.com/annotated-links/documentation/2020/... but I'm not seeing what I really want just yet.
- rglullis 6y ago
  I am afraid I won't be able to help you much there. Every place I saw trying to come up with a grand top-down scheme to organize documentation failed. Too much structure, and people will wait until they have all of the details needed to start contributing, or they will not contribute unless it's "their job". Too much flexibility and they don't know where to start. I found that it was always better to let documentation and knowledge sharing follow the same principles as code: let it come bottom-up, see what patterns emerge and only worry about structure when the current practices hit a bottleneck. But then again I never worked on any project that I had hundreds of people directly depending on the documentation, so it might not work as a strategy for larger-scale organizations.
curryst 6y ago
> The solution we had was to give one Space for each team/department in the company This is the single biggest tip I would give any company who uses Confluence. For some reason, most companies I work for that use Confluence insist on using minimal separation of Spaces. I.e. IT in general has a Space, and my team has a folder nested 6 folders deep in some path that I can never remember and have to bookmark. It makes search effectively useless. If I search for "X api documentation" I get 10,000 results ranging from meeting minutes that some unrelated team put up that just happen to use those terms, to pages from other teams documenting how they use the API. A Space should be treated the same as a Jira project. If I had my way, I would create a Space every time we created a Jira project. And my biggest request for the Confluence team would be better markdown support (I should be able to indicate that I want to type Markdown without having to click through a giant list), and a way to set up a space to sync from Markdown files stored in Git. Some of us don't want to use the WYSIWYG editor, and I would love to be able to use an MR review process for documentation changes before they go live.
- rglullis 6y ago
  From Steve Yegge's famous Rant about Google not understanding platforms: So one day Jeff Bezos issued a mandate. He's doing that all the time, of course, and people scramble like ants being pounded with a rubber mallet whenever it happens. But on one occasion -- back around 2002 I think, plus or minus a year -- he issued a mandate that was so out there, so huge and eye-bulgingly ponderous, that it made all of his other mandates look like unsolicited peer bonuses. His Big Mandate went something along these lines: All teams will henceforth expose their data and functionality through service interfaces. Teams must communicate with each other through these interfaces. There will be no other form of interprocess communication allowed: no direct linking, no direct reads of another team's data store, no shared-memory model, no back-doors whatsoever. The only communication allowed is via service interface calls over the network. It doesn't matter what technology they use. HTTP, Corba, Pubsub, custom protocols -- doesn't matter. Bezos doesn't care. All service interfaces, without exception, must be designed from the ground up to be externalizable. That is to say, the team must plan and design to be able to expose the interface to developers in the outside world. No exceptions. Anyone who doesn't do this will be fired. Thank you; have a nice day! I think about that a lot when designing any system, machine- or human-centered, that needs to communicate with a disparate group of entities. Encapsulate the implementation details to those who are closest to the actual information and have enough power to take action, and make the contact interfaces very explicit. This alone will get you 85% of a functional system. The rest is just selecting actors in your system that know how to cooperate and understands these boundaries.

phixiuz 6y ago

Also have similar experience with Confluence, as an alternative: we adopted a VuePress static site that we host internally (behind proxy), which basically just renders a bunch of markdown files. For easy discoverability of content we use Algolia's documentation search on top of it. For updating content we either use git locally for technical people, non-technical people can also directly update the content on remote git via gitlab interface. This has been working really well for us once setup, the main challenge we still have now is how to effectively communicate changes to the relevant people at the most appropriate time. Your knowledge system keeping in sync with your version control is also a major plus, this is the primary reason why I don't like tools like Confluence, because it's easy for them to get out of sync with the actual system, and this can require too much coordination.

rglullis 6y ago
> it's easy for them to get out of sync with the actual system, and this can require too much coordination. I don't follow. How much do you have of your non-techies updating your knowledge base and how do they get to know if what they are updating is "in sync" with the system if the changes are making are orthogonal with the functionality? It seems your case is mostly about documentation of the technical product, specs, requirements. Yeah, this can go to your version control, and I would bet that you could find a Confluence plugin that would generate the documentation from version control and sync with the rest of your Confluence pages if you wanted. But I really, really doubt your method can scale beyond the IT side of any middle-to-large organization. The moment you ask Business/Customer Support people to actually go look at anything like Gitlab/Github's interface is the moment you lose 90% percent of buy-in from both non-techies and management at any company that is not absolutely dominated by Software Engineers. Requiring integration with version control is a convenience for engineers, but it is so far from the tooling from those that live on Excel sheets that you might as well ask them to never touch the documentation side.
- phixiuz 6y ago
  Granted, we're still a fairly small organization (+- 10), but our business and customer support people are also using Gitlab to maintain our knowledge base: once you properly guide them on how to use it, they are definitely able to handle this. All the actual git operations happen under the hood of the web interface. So we do strongly believe this is scalable, at least for our use case. This has been working fine in fact for long-lived information across multiple departments (not only technical docs, but also e.g. sales/customer support guidelines). For short-lived information we use Google Docs (e.g. meeting summaries).