I guess I am in the minority of devs - I am a fan of project management tools, particularly confluence and jira.<p>I switched into tech from finance, where your projects management tools are multiple email threads on the same topic and an excel spreadsheet that gets emailed around for people to update.<p>Yes, it could be better, but I am happy that it is not a lot worse.
You know, I don't hate <i>most</i> aspects of Confluence, except I find the editor to be <i>terrible</i> (at least in the way it's configured in my workplace). I find that I inadvertently change fonts all the time, I can never really get code formatting to work, the I find the controls to be counter-intuitive. Granted, a lot of these are sort of inherent to WYSIWYG editors, but I guess I just really want them to add a true "write in markdown instead of a WYSIWYG".<p>Because of this, I do all my notes in Obsidian, which I like a lot, but there's something sort of inherently problematic with this: a lot of the notes I take about how things work (e.g. build steps, relevant links, code snippets, code "gotchas") should <i>probably</i> be shared with the team, but it's such a pain in the ass for me to put onto Confluence that I don't bother.
> neither are you ever going to use Confluence as a filesystem storage to replace Google Drive. This means that your knowledge’s single-source of truth needs to accept external tools content as possible documentation. This interfacing, though, can’t simply be about linking files and urls in one place, it has to be deeply integrated so that it feels natural, native even. We should be able to put a Google Sheet file in a folder, attribute tags for example.<p>What's wrong with using just links?<p>(reads to the end)<p>Oh, it's lowkey a promotion for his product it must obviously have this native interfacing that he's hyping up about. I honestly don't see what the problem is with keeping a collection of links to Gdocs/Gdrive/Figma in the knowledge base. That's pretty much the only guaranteed way to use these tools, because all of them want to silo you into their website.
I really don't have the hatred for these Confluence products that most around here seem to have. Sure, there's some quirkiness in writing in the Confluence WIKI, especially now that there's also no behind the scenes confluence-based markdown mode, like we used to have.<p>And regarding JIRA, I'm guessing it's because more people around here are working on small single focused teams, or early stage startups, and don't really appreciate the power of JIRA to orchestrate delivering complex features that span multiple different groups at an org. At a base level, creating simple JIRA task tickets for a single teams scrum is just so damn easy, and devs looking at their assigned work for the sprint, is pretty easy. And it basically integrates with all the tools devs use, from Emacs to Slack, etc....<p>I'm really not sure what alternatives people are into? Also, these current tools are such a huge step forward from what we used to use a decade ago...
The world really needs "one ring to rule them all". (e.g. something that sucks in content from all those places and makes them organizable if not findable)<p>I worked at a startup where, every two weeks, we had a retrospective meeting and the complaint went around that we had too many places to store documents and that we couldn't find them.<p>Often the same people who were complaining would tout that we add a (N+1)th place to the N places we already had (N>20 by this point.) I'd be the only one to point out the irony in this, people wouldn't get that it was ironic, management would approve, and it would happen again two weeks later.<p>It might have been funny except for this: it got us in trouble when we were collaborating with customers and customers would get mad that we were sharing documents in ways they thought were insecure. When it happened more than once with the same customer, we lost some very good customers.
A previous company I worked for had a team who’s whole job was keeping the kb up to date.<p>If you wrote an article/page they would schedule a recurring 6 month meeting with you to go over it and confirm it was still accurate and relevant. If you missed the meeting more than once in a row they would archive your doc until it could be reviewed. You also had to identify a secondary domain expert for that article who could step in if you left the company. The process worked pretty well.<p>As others pointed out here, it’s a process issue that is hard to solve with tech.<p>The people at the top need to buy into the idea that a good kb makes everything run smoother and be willing to pay for it (ie hire more heads just for kb maintenance).
The hatred for atlassian products, IMO, has a root cause in a few facts:<p>1) it's an enterprise product, so the typical enterprise issue of: it's not being sold to the users, the people who it's being sold to don't have to feel the pain, and checking off features is more important than UX.<p>2) that said, it's not the worst enterprise. It is possible to configure atlassian products to have a really smooth UX (can't say the same about speed, the last I used atlassian, it was really, really, slow though that may have changed). However, wrangling the product (and its users) is almost a full-time job, and atlassian is known to have breaking transitions that mess up your workflow with no recourse to go back to classic. Change management is hard.<p>3) a lot of higher ups who make the choice of using atlassian even if they are technical and once were a user of atlassian products, used it in an era where it was simpler or worked in an environment where they were privileged enough to have a full-time wrangler from 2)
This post makes some salient points about the challenges of team knowledge sharing:<p>- Tree structure is too strict for cross departmental content ex sales to customer success handoff - should that be under sales or customer success?<p>- The right answer can be found in multiple tools - companies are not going to ditch Google Sheets / Excel for Notion tables<p>- A common source of truth needs to take into account the variability in skill - some users are going to be heavier users or more technical than others<p>- Collaboration needs to be as good as Google Docs or else people will just use Google Docs<p>It looks like the author is envisioning a new solution with Dokkument but if you want an existing one, take a look at <a href="https://slab.com" rel="nofollow">https://slab.com</a>. It’s designed to focus on team knowledge sharing while recognizing that it will be part of the productivity stack. For example, there is have a Content Map feature that shows a bird’s eye view of the entire information topology (with filters and drill down possible) and even mass reorganize from there. Integrations are first class with search retrieving results from other tools and rich linking that will preview external content. Knowledge sharing used to be an afterthought for a lot of teams but with the world going remote it’s exciting to see the innovation and prioritization pick up in this space.<p>Disclosure: I am a co-founder of Slab
The depressing irony of all this is that despite the massive advances in technology in software and hardware, this kind of tooling, specifically document/content/knowledge/issue management has remained stuck in its containing medium, be that word documents on a shared drive, or textareas on a web page (as I am typing in right now!)<p>It seems that smalltalk-like systems, and derivatives such as the lively kernel contain clues as to what a unified meta-interface to an individual's or organisation's content might look like (and how it might behave). Integration and user adoption is a difficult problem (in general) though -- probably the best example of this is the poor (and in some circles, pretty vile) criticism that Google Wave received, though this type of feedback is probably due in part to a lack of understanding of the problem being solved.<p>"The content revolution hasn't happened yet!" [1] :-)<p>[1] with apologies to Alan Kay, <a href="https://www.youtube.com/watch?v=aYT2se94eU0" rel="nofollow">https://www.youtube.com/watch?v=aYT2se94eU0</a>
Over the decades, I've set up many engineering and organizational document processes, and I've also been a developer on doc tools. The culmination of all of this is that I've ended up gravitating to very-low-friction, tracked, centralized doc -- code-embedded API docs and Markdown files in the/a repo -- and sometimes also a Wiki (preferably a Wiki of the same platform that hosts the repo, unless you've made it hard for non-developers to access the repo platform).<p>But, if I absolutely have to, I'll endure Confluence. Only if people agree to stop throwing away important information into a dozen different other SaaSes and tools that are effectively write-only, as far as the organization is concerned. Don't just turn those 12 memory holes into 13.
I have come to believe that tools will never solve philosophy-of-use problems. This solution may not scale, but I am confident that a team of 5-10 technical writer/archivists/internal consultants under the command of an extremely rigorous leader could handle widespread documentation for a company of 100-200 people just by using a LaTeX/Git/Wiki stack.<p>This is related to problematic changes in the field of requirements management. A few decades ago, various companies invented technical requirement databases for large-scale engineering projects, and moved their document-based teams onto these new databases (DOORS, etc.)<p>Engineering managers think it's like this: Databases (good) > Documents (bad), and they get paid by the metric. And that's the <i>good</i> managers. The bad managers hate changing anything and want to stay with documents.<p>This, unfortunately, is a reduction of the problem. Most requirements teams didn't have a robust architecture for writing and storing requirements even in their document-based method. The actual hierarchy goes like this: Database with excellent plan (best) > Documents with excellent plan (good) > Database with no plan (bad) > Documents with no plan (worst). Most legacy requirements engineering teams have <i>no idea</i> just how bad the situation is, and have no desire to improve their consistency or internal organization.<p>This attempt to replace documents with databases seems to be analogous for the modern software company attempt to shift from hard docs to widely-accessible wiki-style docs, or at least it certainly is at the pure software company I work for now (I came from more tangible engineering). Rules for storing documentation are almost more important than the documentation itself. My current team generates documentation at a very large rate; it's completely unsynchronized, the articles vary stylistically and structurally, the linking is inconsistent, and labelling is nonexistent across divisions. We need a hierarchical documentation structure imposed on us tyrants, consulted by the company-specific subject-matter experts. It's like comedy--much easier to write a sketch about broccoli than it is to write a sketch about anything.
I generally find these sort of diatribes against the market leading project management tools a little pointless. Another popular topic that also has numerous "we deserve better" articles is email.<p>The fact of the matter is solving those problems, while solving all the incredible long tail of corner cases, is incredibly difficult. You can theorize how things should be done and try to "rationalize" your way into some sort of ideal product, but as we've seen plenty of times, they eventually end up with a product that looks like an existing product (see Asana's evolution for example). It doesn't mean you shouldn't try, because my hunch is there's probably some sort of thing that just hasn't "clicked" yet, and the moment a product is able to do that, suddenly it'll become the most obvious way to do things. Until then companies will keep trying because it's an incredibly lucrative space, and there'll always be a new trendy system out there (Monday.com for example). But most of them end up being inferior in most ways, and superior in just 1 or 2 ways which forces the hand of larger companies to just to choose the larger one anyway.<p>Good luck to Dokkument in trying to get there. In this space you either die a hero or live long enough to become the villain.
Any confluence like tool (wiki/sharepoint) is only as good as the people who populate, edit, and curate it. The tool itself (confluence) is generally not a problem, the problem is that documents go stale and/or are badly organized. You can't really automate yourself out of that problem. Just because any given document hasn't been touched in months or years doesn't mean it's actually out of date.<p>I remember for about 5 seconds in late 90s early naughts there was talk of this role of 'information architect', a sort of a digital corporate librarian. I imagine such a role should still exist, but who has the headcount?
I wonder if part of the issue (on top of the software itself being poor, and obvious point that human problems are hard), is that nobody ever seems to hire a design team for internal stuff until far too late in the game (if ever).<p>Many of the problems with internal knowledge bases could be lessened if there was an IA, whose job it was to iterate on improving the organisation of internal knowledge. They wouldn’t do it alone, they’d need company-wide buy-in, but what I typically see is that it’s a complete free-for-all or it’s owned by HR/People (also bad in my opinion).
I’d like to just open JIRA or Confluence and not have a dozen call-to-action notifications strewn about the UI about (new feature no one asked for or cares about) I have to manually close.
Sometimes I feel like the only person in the world who actually likes using Confluence.<p>Jira...I can definitely see why people have issues. But confluence has always been rock solid for me and easy to use.
Things I would like to see in a knowledge base:<p>* built in document aging and asset maintenance strategies - ideally including a time estimate for billing. A document not worth maintaining is not worth having.<p>* similarly some sort of automated / well-designed change management component - I changed this codebase / design component / business offering / org chart, what knowledge bases are affected<p>* and similarly a much more intelligent (and harsh) judger of documentation, Wiki content etc - the human curator today comes back to the room and says, "everything we have is old or sh!t," the KB comes back with "31 pages of results!" Infuriatingly shallow experience.<p>* graph and Venn diagram representations of viewer/authors and tags/topics, metadata, etc with killer app search and browse capabilities. Eliminate hierarchies, embrace dependencies
Never ceases to amaze me how people are so quick to slap a "made for tech teams" onto their landing page — in an attempt to say they're for the entire company.<p>Exactly what is made for tech teams? All I see is generic features in there.<p>Confluence, Notion and Dokkument and all the tools are not made for tech teams. They are just generic editors and organizers. Notion stands out in the fact they are trying to cross boundaries from the docs space, into the project management space, and into the data management space.<p>Again, do we see API docs in any of these tools? Do we see integrations to GitHub, OpenAPI/Swagger, GraphQL, software architecture diagrams, changelogs, great markdown support? Do we see great care in keeping the software fast as required by tech people?<p>It didn't seem that way to me when I started building archbee.io — it's truly made for tech people.
This seems as much about the weaknesses inherent to ad-hoc taxonomies as anything. Once you give people the means to organize their stuff into trees, you always get a few folks who go hog wild and get a little too fixated on divvying things up.
I hate to admit it but the best tool I've used recently for this is Slack search. Any attempts to find documenation where the company tried to "manage knowledge" led to an endless trail of outdated documentation and frustration. I've come to terms that it's near impossible to keep this stuff current and that it's actually more dangerous to have a system that gives you false confidence in its accuracy.
How hard is it to make consistent search? I can accept no partial matching, even if I preferred to have one. But at the same time there is some fuzzy logic matching words with entirely different meanings, when in tech I often need want to search for very specific word. Not some mangled version of it... Who is these products made for again exactly?
I wish more posts on documentation talked about some of the principles that make similar documentation platforms excel. Specifically, there has been hugely positive feedback from engineers about g3doc: <a href="https://www.youtube.com/watch?v=EnB8GtPuauw" rel="nofollow">https://www.youtube.com/watch?v=EnB8GtPuauw</a>
That looks very similar Timorese document management systems out there. We’ve been using Alfresco very successfully as a knowledge management system since it preserves everyone’s flow in terms of tools. Devs have their Markdowns, business has ODTs, etc.
The biggest problem about knowledge management is that it gets stale pretty fast, and people don't see it as part of their job to keep it up to date.<p>That's more like organisational problem, but I'd wanted to tackle it from tech point of view, I would look into some mechanism that would ping people periodically to make them review and update their docs - email notifications, cross peer review, something along these lines.
I'm convinced that the only thing keeping people using Atlassian products is naive managers and antiquated IT/Ops staff who've learned that mentioning "Jira", "Confluence", etc. in the presence of their seniors results in some micro-fractional justification of their existence.<p>To paraphrase Thomas Sowell: "The least productive people are usually the ones who are most in favor of [using Atlassian products]".