We deserve better than Confluence and Notion(blog.luap.info)
blog.luap.info
We deserve better than Confluence and Notion
https://blog.luap.info/we-deserve-better-than-confluence-and-notion.html
114 comments
Confluence squarely falls into the intranet trap. The only intranet/wiki/etc that anyone likes it the new one, no matter the product/technology. Old document stores gather cruft, aren't maintained, and become full of incorrect information over time.
Eventually, you start over (MediaWiki -> SharePoint -> Confluence -> something else) and the new one is great (Confluence is awesome) and the old one is passe (Sharepoint sucks!). Nobody has solved the fundemental problems around intranets.
Eventually, you start over (MediaWiki -> SharePoint -> Confluence -> something else) and the new one is great (Confluence is awesome) and the old one is passe (Sharepoint sucks!). Nobody has solved the fundemental problems around intranets.
To be fair, SharePoint always sucked and was never any good.
Agreed. I work for a big corp that uses sharepoint - I would take a poorly set-up confluence / jira workflow any day.
Sharepoint sucks where I am because IT can't leave our URLs alone. thus there is old information out that that would be useful if I could find it. And other old information that I tried to update but I couldn't find it anymore.
I long ago made a personal rule that when someone asked a question I would answer by pointing them to the documentation. If the documentation doesn't exist or isn't up to date I'd fix it first. So long the the URLs (and thus the index pages) don't change I had a large store of useful information. This is the only way I have found to ensure document stores don't gather cruft.
I long ago made a personal rule that when someone asked a question I would answer by pointing them to the documentation. If the documentation doesn't exist or isn't up to date I'd fix it first. So long the the URLs (and thus the index pages) don't change I had a large store of useful information. This is the only way I have found to ensure document stores don't gather cruft.
I'm with you on this one. I love confluence.
It's web based so no installation hassle.
It allows the raw storage of documentation.
It allows you to search uploaded documentation.
It allows you to easily search everything! At my last company, someone pointed out to me that I could find almost anything I wanted to know about existing systems in our confluence.
It is excellent for collaborative editing.
It is excellent for writing and formatting documentation that must be shared.
It has a wide variety macros and plugins that let you effortlessly embed charts and diagrams. Admittedly, some macros (ie gliffy) are vastly superior to others (lucidchart).
You can write good documentation with minimal effort. But it also provides a comprehensive set of tools to format the crap out of your documents if you want to.
At this point, I'm really struggling to figure out what someone actually wants out of a "perfect" product. A lot of the things the author complains about would require draconian solutions from a systems standpoint that would just set off another round of complaints that the system is to restrictive.
It's web based so no installation hassle.
It allows the raw storage of documentation.
It allows you to search uploaded documentation.
It allows you to easily search everything! At my last company, someone pointed out to me that I could find almost anything I wanted to know about existing systems in our confluence.
It is excellent for collaborative editing.
It is excellent for writing and formatting documentation that must be shared.
It has a wide variety macros and plugins that let you effortlessly embed charts and diagrams. Admittedly, some macros (ie gliffy) are vastly superior to others (lucidchart).
You can write good documentation with minimal effort. But it also provides a comprehensive set of tools to format the crap out of your documents if you want to.
At this point, I'm really struggling to figure out what someone actually wants out of a "perfect" product. A lot of the things the author complains about would require draconian solutions from a systems standpoint that would just set off another round of complaints that the system is to restrictive.
Confluence and JIRA both depend on how your company configures them.
They can both be set up to be incredibly useful, or completely useless.
Typically, the more configuration was decided by someone who doesn't do technical work, the more they slide towards the latter. In most companies, they're configured exclusively by people who don't do technical work (e.g. HR).
They can both be set up to be incredibly useful, or completely useless.
Typically, the more configuration was decided by someone who doesn't do technical work, the more they slide towards the latter. In most companies, they're configured exclusively by people who don't do technical work (e.g. HR).
> It allows you to search uploaded documentation.
> It allows you to easily search everything!
The first one is correct. Confluence will happily search PDFs uploaded to pages. Search in general is... well it's not good. Confluence very much requires that you know exactly what you're searching for and roughly where it is. Unless it's a PDF. In that case it will be the top result for 8 out of 10 searches.
That being said I still think Confluence is one of the best documentation platforms available. It's a little sad that Atlassian is discontinuing the server version (datacenter still exists). Many of their customers simply cannot legally use their hosted option. I know we have at least two customers who are absolutely screwed when they reach EOL on their on-prem installation, because they cannot afford datacenter licenses.
> It allows you to easily search everything!
The first one is correct. Confluence will happily search PDFs uploaded to pages. Search in general is... well it's not good. Confluence very much requires that you know exactly what you're searching for and roughly where it is. Unless it's a PDF. In that case it will be the top result for 8 out of 10 searches.
That being said I still think Confluence is one of the best documentation platforms available. It's a little sad that Atlassian is discontinuing the server version (datacenter still exists). Many of their customers simply cannot legally use their hosted option. I know we have at least two customers who are absolutely screwed when they reach EOL on their on-prem installation, because they cannot afford datacenter licenses.
Oddly, to your first point, I've had exactly the opposite experience. Came from a company that used sharepoint for almost everything, that I referred to as /dev/null - if you didn't know EXACTLY what you were looking for, search was useless after you uploaded or created something. It was not uncommon for the document with matching search terms in the title, to show up on page 3 of the results.
Moved to a company that used Confluence for almost everything (there was already a fair bit of content), and search was an absolute dream. Even with terrible search terms, the page (or document) you were looking for was invariably in the first 3 results.
If only JQL was available for Confluence...
Same. They absolutely fall into the category of "worst tools available except for all the others". It takes work to configure a JIRA workflow and set of dashboards that works for your org, but every other product I've tried just doesn't even try. I was really shocked the first I tried Notion and Asana since they were so hyped, but they felt way to simple to be useful. Even with a small team we found them way too confining.
I'm ok with confluence too. It used to be slow, nowadays it seems to be fine.
I think the real problem is "writing is difficult." I used to write blogs, now I don't do it anymore. it's too involved.
could there be another form of content that's easy to create? like audio and video (with searchability ).
I think the real problem is "writing is difficult." I used to write blogs, now I don't do it anymore. it's too involved.
could there be another form of content that's easy to create? like audio and video (with searchability ).
You know, I don't hate most aspects of Confluence, except I find the editor to be terrible (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".
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 probably 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.
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 probably 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.
I'm in the same boat. Most of my notes transfer over just fine because it's Markdown, but Confluence handles in-lining LaTeX significantly worse than pretty much any other CMS I've ever used.
I forgot about equations!
Obsidian sadly still only really supports the typical Mathjax stuff, so I can't do really cool and advanced LaTeX like I would if I were using Pandoc or something, but sadly I feel like really good equation support is still something that most note-centric apps care a lot about.
Obsidian sadly still only really supports the typical Mathjax stuff, so I can't do really cool and advanced LaTeX like I would if I were using Pandoc or something, but sadly I feel like really good equation support is still something that most note-centric apps care a lot about.
For an online shared Markdown note taking, try hackmd.io.
The issue is that it's not useful unless I can get my entire team to really use it, and more importantly get the company to sign off on it. If I want to write down and share anything proprietary with a third-party service, I need IT/corporate sign off on it.
I can do Obsidian because it just runs locally on my computer, and I could do Confluence since corporate has signed off on it, but if I try doing a random markdown website, I think someone would smack me.
I can do Obsidian because it just runs locally on my computer, and I could do Confluence since corporate has signed off on it, but if I try doing a random markdown website, I think someone would smack me.
> 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.
What's wrong with using just links?
(reads to the end)
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.
What's wrong with using just links?
(reads to the end)
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.
Except you can open them in an iframe. Which is what Dokkument (the product being promoted by the author) is doing. Not sure how much more useful that is than simply opening it in another tab which would work 100 times better since you won't have to jump a ton of hoops to make sure everything works fine.
The link methods works fine for tech people, but less for non technical ones. By displaying directing the content you save one click and you make the workflow more natural (and it also gives the idea to do it, if a user see a link in a blank document he will like "meeh why would you do that", whereas when you see an iframe, you get the logic easily). Also the iframe is the first step, the next step is to directly interface with Google, Github and others via API, so that you can manage rights, creation, deletion, .. and the user only has to choose which type of document he wants to create.
You should also probably look at T&C of the services you are embedding to see if they allow it.
There's a limit to how much integration you can add via an API. Not to mention that a lot of services don't even have an API or have outdated ones.
> By displaying directing the content you save one click and you make the workflow more natural (and it also gives the idea to do it, if a user see a link in a blank document he will like "meeh why would you do that", whereas when you see an iframe, you get the logic easily).
Not sure what you mean here by "link in a blank document". Why not just directly open the 3rd party app in a new tab when you click on an entry in a side menu? There's no click saving, really. You are just embedding the tab that'll be opened.
The other problem is that most apps are not built to be embedded in an iframe. While they might appear to work normally initially, one click could break them because iframe is not the same thing as a normal browser window. Of course, you could provide various workarounds for it but the experience will be subpar at best.
There's a limit to how much integration you can add via an API. Not to mention that a lot of services don't even have an API or have outdated ones.
> By displaying directing the content you save one click and you make the workflow more natural (and it also gives the idea to do it, if a user see a link in a blank document he will like "meeh why would you do that", whereas when you see an iframe, you get the logic easily).
Not sure what you mean here by "link in a blank document". Why not just directly open the 3rd party app in a new tab when you click on an entry in a side menu? There's no click saving, really. You are just embedding the tab that'll be opened.
The other problem is that most apps are not built to be embedded in an iframe. While they might appear to work normally initially, one click could break them because iframe is not the same thing as a normal browser window. Of course, you could provide various workarounds for it but the experience will be subpar at best.
> Why not just directly open the 3rd party app in a new tab when you click on an entry in a side menu?
Because you lose the ability to give tags, attributes, page comments, document feedback. For example, there is no comments in a Google Sheet, by embedding them in a page with comments, you can have comments, you can also give it tags and all ...
> While they might appear to work normally initially
Even Github doesn't allow iframe embedding. The goal is to facilitate discovery, if you need to use the app, you would open it in its own tab. A chrome extension would help going back to Dokkument from Github, or add a github file into dokkument and also bypass the iframe protection.
The whole point of the app is to facilitate discovery and sharing following a common framework, we are only a hub and redirect users
Because you lose the ability to give tags, attributes, page comments, document feedback. For example, there is no comments in a Google Sheet, by embedding them in a page with comments, you can have comments, you can also give it tags and all ...
> While they might appear to work normally initially
Even Github doesn't allow iframe embedding. The goal is to facilitate discovery, if you need to use the app, you would open it in its own tab. A chrome extension would help going back to Dokkument from Github, or add a github file into dokkument and also bypass the iframe protection.
The whole point of the app is to facilitate discovery and sharing following a common framework, we are only a hub and redirect users
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.
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....
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...
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....
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)
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.
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.
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.
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.
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.
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.
not the world, just your team or company or project. Some tools are better suited than others depending on the team/company/project.
But yep you’ve gotta have just one, more and the network effects break down rapidly - at which point it’s no longer a useful tool.
But yep you’ve gotta have just one, more and the network effects break down rapidly - at which point it’s no longer a useful tool.
> 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)
We have those, we call it filesystem or fileserver.
We have those, we call it filesystem or fileserver.
I knew which one it was before clicking the link.
Proof that xkcd links are the real-life equivalent of the prisoners yelling numbers instead of jokes
(Context: https://onemansblog.com/2010/05/18/prison-joke/ )
(Context: https://onemansblog.com/2010/05/18/prison-joke/ )
A previous company I worked for had a team who’s whole job was keeping the kb up to date.
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.
As others pointed out here, it’s a process issue that is hard to solve with tech.
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).
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.
As others pointed out here, it’s a process issue that is hard to solve with tech.
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:
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.
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.
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)
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.
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.
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)
You don't understand the hatred for Atlassian until you've been around long enough to notice there's a cycle: 1. We hate X. 2. "Here's a lightweight replacement Y for it!" 3. Lightweight replacement Y is forced by the problem space to become as big as what replaced it. 4. We hate Y.
I'd guesstimate the hatred for Atlassian productions is about 75% simply the fact that anything that checks all the boxes necessary to become the enterprise standard will be something that is big and bloated and hated by the users, because Atlassian is merely the latest in a long line of systems hated by people.
Which is not to say anyone should change their mind about the product. Just bear in mind, there isn't anything better that, if it did somehow unseat Atlassian, wouldn't have exactly the same problems in 3-5 years. The problem is the problem space, not the solutions. I mean, sure, I'd like Atlassian to be faster and I suspect there's some room for improvement there, but even if they put a lot of work into it the problems would remain. The problem is that everyone thinks they mean the same thing by issue management, but when you sit down to actually see what that means, it turns out to be the leading bug tracker or wiki means you actually have to be a meta-bug tracker or a meta-wiki, and that's never going to be a great product.
I'd guesstimate the hatred for Atlassian productions is about 75% simply the fact that anything that checks all the boxes necessary to become the enterprise standard will be something that is big and bloated and hated by the users, because Atlassian is merely the latest in a long line of systems hated by people.
Which is not to say anyone should change their mind about the product. Just bear in mind, there isn't anything better that, if it did somehow unseat Atlassian, wouldn't have exactly the same problems in 3-5 years. The problem is the problem space, not the solutions. I mean, sure, I'd like Atlassian to be faster and I suspect there's some room for improvement there, but even if they put a lot of work into it the problems would remain. The problem is that everyone thinks they mean the same thing by issue management, but when you sit down to actually see what that means, it turns out to be the leading bug tracker or wiki means you actually have to be a meta-bug tracker or a meta-wiki, and that's never going to be a great product.
As my career progresses I find myself increasingly leaning towards opinionated tools that sell a methodology more than flexibility, for exactly this reason.
Yea I want tools to be similar how I write programs. Solve one problem and solve it well. If you need more functionality, write another small program for that problem and integrate.
Integrating can be tricky, but having one tool try to do everything usually means it does nothing well.
Ideally we will see more effort spent on straightforward, opinionated tools that allow integration. That’s my hope at least.
Integrating can be tricky, but having one tool try to do everything usually means it does nothing well.
Ideally we will see more effort spent on straightforward, opinionated tools that allow integration. That’s my hope at least.
This is fundamentally a sales problem, more than a constant.
New large customer X wants feature Y. Your product does not currently Y. What do you do? It's hard to say "No." Especially when you have growth to maintain, revenue targets to hit, VC to please, etc.
To me, "opinionated" means "have a vision of what the product is and isn't" (that is strong enough to counter-balance sales pressure).
New large customer X wants feature Y. Your product does not currently Y. What do you do? It's hard to say "No." Especially when you have growth to maintain, revenue targets to hit, VC to please, etc.
To me, "opinionated" means "have a vision of what the product is and isn't" (that is strong enough to counter-balance sales pressure).
I completely agree with this.
At a few of the start ups I've worked at, "no" wasn't in the dictionary.
It was always a dumpster fire, the product had some many configurations and options. There were entire sections of the apps I didn't know existed. I think that all these features are ultimately what killed the start up.
At one point I (developer) had to go on a call with a customer to tell them no because the PM didn't want to disappoint the customer.
Learning to say no is extremely important for startups.
At a few of the start ups I've worked at, "no" wasn't in the dictionary.
It was always a dumpster fire, the product had some many configurations and options. There were entire sections of the apps I didn't know existed. I think that all these features are ultimately what killed the start up.
At one point I (developer) had to go on a call with a customer to tell them no because the PM didn't want to disappoint the customer.
Learning to say no is extremely important for startups.
Customized branch, supported at xxxx or xxxxx or xxxxxx per year.
I hate Confluence infinitely less than I hate Sharepoint -- which is also mentioned in the article. Both of them market themselves as filling the same corporate overlord niche role. One of them even vaguely succeeds.
There’s a few products that I feel bad for the devs and people associated with. I really feel bad for SharePoint devs because it doesn’t seem like it should be as horrible as it is.
Like everything simple (let’s make a wiki tied to AD) is twisted around to make it complex and confusing so it’s lock-in forever.
The per user cost for SharePoint is like $100-200/year. Think about that for a minute. That’s really high for a wiki. And cheap for an enterprise knowledge workflow. But it sucks so hard if you want users to create, collaborate, and share info.
Like everything simple (let’s make a wiki tied to AD) is twisted around to make it complex and confusing so it’s lock-in forever.
The per user cost for SharePoint is like $100-200/year. Think about that for a minute. That’s really high for a wiki. And cheap for an enterprise knowledge workflow. But it sucks so hard if you want users to create, collaborate, and share info.
Not disrespecting your pain, but I'm guessing you never had to do serious work in Lotus Notes.
Good point. The last time I used Lotus Notes was 2010. I hated it, but it seemed to be constrained to its e-mail nightmare world. SharePoint, since it’s nominally web, gets stuck into everything.
Comically, SharePoint makes me tolerate Confluence and Salesforce more.
Comically, SharePoint makes me tolerate Confluence and Salesforce more.
Atlassian acquired Trello 4 years ago. Still seems to be doing better than Jira is, although I feel it’s maybe still slightly worse than when it was acquired.
I imagine if a company using Trello wants more features they probably just say “use Jira”.
I imagine if a company using Trello wants more features they probably just say “use Jira”.
There's no need for nuanced analysis. The root cause of the hatred for Atlassian products is that they are utter shit
Completely agree. Jira theoretically could be used to be good, but it's an absolute nightmare to use. Totally inconsistent and muddled UX. Awful graphic design. Worst of all, completely bugged-out word processing, which is the entire point of Jira
the fact that the wysiswyg text editors are not the same between Atlassian products was the giveaway sign to me. They are clearly shipping the org chart, like everyone else.
I hate them, but I almost can't blame the devs. It's extremely difficult to ship anything today at scale without justifying it to extreme growth-focused investors. I bet every single time someone has the chance to say "no, let's slow down and refine this", someone else points to the revenue and contract targets and hits "deploy".
The editors are not even the same between screens in the same product. The task description field uses one editor for the Create Task screen, and a different editor for the Edit Task screen.
What's your preferred alternative for medium to large teams?
That is a good question. It depends on the circumstances and whether or not you're doing highly-regulated and auditable work (medical software, spaceflight databases) or more improvisational free-market stuff (video games, non-essential chat platforms).
Overall, I think my preferred method is to deliberately choose to implement about 15% of Jira's possible functionality but also rigorously define how that functionality can be used used so it's consistent across your entire organization. For instance, Jira has release versions, fix versions, labels, ticket types, summaries, custom fields, etc. However, most of those are really just "other ways to slice the data"., and total freedom allows people to create non-set-complete ways to slice data.
As an example, let's say that I have a list of 400 things--bicycle, pear, jar, cassette tape, ennui, Aristotle, 2. Our Chief Philosophy Officer wants to be notified on any tickets pertaining to philosophy, so he tells our division to tag all philosophy-related tickets as "philosophy" and then starts assigning his own grad students to analyze them.
Well, we just added the "philosophy" tag, implying "a type of label that discusses the academic content of the ticket". Do we have other tags that fit into that label type, like "history" and "science"? Where's the list of possible entries of that tag type? Where's the list of all tag types? Where's the list of all possible tags? What do they mean? Where are they defined? When do I use them? No one knows, because no one has the authority to know, we just keep growing and shipping or else we get the hose again.
By solving a momentary problem--Chief Philosophy Officer wants a set of tickets to look at--we have invented yet another fractious method for looking at an incomplete set of tickets that doesn't actually apply to every ticket, and our Jira ecosystem gets more unwieldy and less complete.
I would instead prefer to either turn the ticket tagging feature off entirely, or I would prefer that the Chief Philosophy Officer not get to dictate what tags are created and instead go through the Tagging Authority Team, which dictates what tags exist, how they can be used, and ensures that all tickets are sortable and categorizable, and well-defined, and self-consistent, and set-complete, and also they version their definitions so you know if a ticket was created under v1.0 of the Jira best-use architecture or under v3.6.
That's why I mentioned earlier that it depends whether or not your team is doing something highly regulated. Anyone who's gone through a detailed software audit from a governing body is thinking either "yeah, we had to deal with this problem" or "man, I should fix our tags". Anyone who can just bang out release versions on any schedule serving any customer would think "that is a ridiculously stupid waste of time, I love tagging anything and forgetting about it, because I only need to worry about the feature for X weeks before we're on to the next thing".
Overall, I think my preferred method is to deliberately choose to implement about 15% of Jira's possible functionality but also rigorously define how that functionality can be used used so it's consistent across your entire organization. For instance, Jira has release versions, fix versions, labels, ticket types, summaries, custom fields, etc. However, most of those are really just "other ways to slice the data"., and total freedom allows people to create non-set-complete ways to slice data.
As an example, let's say that I have a list of 400 things--bicycle, pear, jar, cassette tape, ennui, Aristotle, 2. Our Chief Philosophy Officer wants to be notified on any tickets pertaining to philosophy, so he tells our division to tag all philosophy-related tickets as "philosophy" and then starts assigning his own grad students to analyze them.
Well, we just added the "philosophy" tag, implying "a type of label that discusses the academic content of the ticket". Do we have other tags that fit into that label type, like "history" and "science"? Where's the list of possible entries of that tag type? Where's the list of all tag types? Where's the list of all possible tags? What do they mean? Where are they defined? When do I use them? No one knows, because no one has the authority to know, we just keep growing and shipping or else we get the hose again.
By solving a momentary problem--Chief Philosophy Officer wants a set of tickets to look at--we have invented yet another fractious method for looking at an incomplete set of tickets that doesn't actually apply to every ticket, and our Jira ecosystem gets more unwieldy and less complete.
I would instead prefer to either turn the ticket tagging feature off entirely, or I would prefer that the Chief Philosophy Officer not get to dictate what tags are created and instead go through the Tagging Authority Team, which dictates what tags exist, how they can be used, and ensures that all tickets are sortable and categorizable, and well-defined, and self-consistent, and set-complete, and also they version their definitions so you know if a ticket was created under v1.0 of the Jira best-use architecture or under v3.6.
That's why I mentioned earlier that it depends whether or not your team is doing something highly regulated. Anyone who's gone through a detailed software audit from a governing body is thinking either "yeah, we had to deal with this problem" or "man, I should fix our tags". Anyone who can just bang out release versions on any schedule serving any customer would think "that is a ridiculously stupid waste of time, I love tagging anything and forgetting about it, because I only need to worry about the feature for X weeks before we're on to the next thing".
I'm not defending Jira but I heard someone once say that Jira is ugly cause it's a mirror and you're a corporate process
That is extremely true, but I think it's ugly on a screen-to-screen basis. Random text justification, no distinction between editable and non-editable text, various shades of boring/corporate off-white to distinguish sections of the screen, and literal bugs in the software, like you make a table and then when you save the ticket it changes your lower 5 rows to columns in a single row.
Bitbucket is mostly fine, though we seem to be having trouble with it every week nowadays.
However Jira is the worst product I've been forced to use at work since Lotus Notes. If my hatred for JIRA had mass I would collapse into a black hole.
However Jira is the worst product I've been forced to use at work since Lotus Notes. If my hatred for JIRA had mass I would collapse into a black hole.
Well yeah but maybe there's something to learn from it... Or at least prompt some soul searching about the question of "how do I build an enterprise product that doesn't eventually fall into the cesspool of shit"? Is it even possible?
As addendum to 1, this also means it's often seen as the technological hammer with which to get rid of organizational problems, without having to put management effort into solving them first. That can't not end in tears, no matter which particular hammer is directed at your thumbs.
I think this is what drives a lot of the workflow usability issues with JIRA.
A bug not being tested fully, a developer working on a ticket that a PM didn't approve, a fix with no time logged... these are organizational problems. Yet the JIRA hammer lets you "fix" them by restricting workflow actions to certain users and making dozens of custom and required fields.
The result is a downward spiral: people avoid using it because it's painful and always getting in the way, which means no one puts extra effort in to link tickets together, write good descriptions/comments, or fill in non-required fields. The whole system becomes less useful overall, and in the worst case causing more workflow rules and required fields to be added.
It's sad, because JIRA can be good (though: slow). JQL is awesome if your tickets contain good data (after all, garbage-in garbage-out). It's very possible to have well formatted content that's easy to read. The "screens" customizations for transitions can make things faster by showing useful fields at just the right time. And the automations possible by integrating with PRs and builds can save even more time and prevent mistakes.
But all that can (and is) horribly abused to make something that is awful.
A bug not being tested fully, a developer working on a ticket that a PM didn't approve, a fix with no time logged... these are organizational problems. Yet the JIRA hammer lets you "fix" them by restricting workflow actions to certain users and making dozens of custom and required fields.
The result is a downward spiral: people avoid using it because it's painful and always getting in the way, which means no one puts extra effort in to link tickets together, write good descriptions/comments, or fill in non-required fields. The whole system becomes less useful overall, and in the worst case causing more workflow rules and required fields to be added.
It's sad, because JIRA can be good (though: slow). JQL is awesome if your tickets contain good data (after all, garbage-in garbage-out). It's very possible to have well formatted content that's easy to read. The "screens" customizations for transitions can make things faster by showing useful fields at just the right time. And the automations possible by integrating with PRs and builds can save even more time and prevent mistakes.
But all that can (and is) horribly abused to make something that is awful.
Well said. One of the better companies I've ever worked from had a strong "pull culture" for this reason.
Aside from the very rare exception, IT (and IT leadership) was prohibited from pushing tools onto users.
They built tools or sourced and implemented products, and users either adopted them or didn't. This seemed to create a much healthier adoption and feedback loop.
It's ironic that companies praise free market capitalism... and then internally implement command economies (and are flabbergasted by the resultant inefficiencies and supply/demand mismatches).
Aside from the very rare exception, IT (and IT leadership) was prohibited from pushing tools onto users.
They built tools or sourced and implemented products, and users either adopted them or didn't. This seemed to create a much healthier adoption and feedback loop.
It's ironic that companies praise free market capitalism... and then internally implement command economies (and are flabbergasted by the resultant inefficiencies and supply/demand mismatches).
> It's ironic that companies praise free market capitalism...
https://en.wikipedia.org/wiki/Theory_of_the_firm
Note that in "theory of the firm" language, there is a distinction between "markets" and "free market". The "free market" is broader, and subsumes the firm because you have a choice to participate/not participate in any given firm; but it is generally true that within firms you do not operate under market dynamics, and "theory of the firm" seeks to answer both descriptivist and prescriptivist questions about when firms do/should use markets.
https://en.wikipedia.org/wiki/Theory_of_the_firm
Note that in "theory of the firm" language, there is a distinction between "markets" and "free market". The "free market" is broader, and subsumes the firm because you have a choice to participate/not participate in any given firm; but it is generally true that within firms you do not operate under market dynamics, and "theory of the firm" seeks to answer both descriptivist and prescriptivist questions about when firms do/should use markets.
Neat! Thanks for the pointer.
When set in that basic language, I guess my observation was that companies unnecessarily increase internal transaction costs by overly distancing internal buyers and sellers (which I guess in turn forwards into Managerial and Behavioural critiques and explanations, as to "why").
When set in that basic language, I guess my observation was that companies unnecessarily increase internal transaction costs by overly distancing internal buyers and sellers (which I guess in turn forwards into Managerial and Behavioural critiques and explanations, as to "why").
My main complaint against Jira is that it seems to poke the wrong parts of the brain for the wrong type of project manager. It's... fine... on its own, but something about it seems to call out to the hyper-detail-oriented micromanager that makes them want to make 23-step story status workflows. I've come to appreciate opinionated tools that want you to use them a certain way. Even if they prevent me from using them exactly like I'd want to, they also prevent the nightmare PM from using them exactly like they want to.
I understood PMs-from-hell when I finally realized that their work product is detailed schedules.
Whether or not that schedule reflects reality is immaterial. What matters is that it exists and is as detailed as possible.
Which essentially casts the PM as Borgesesque map-maker.
Whether or not that schedule reflects reality is immaterial. What matters is that it exists and is as detailed as possible.
Which essentially casts the PM as Borgesesque map-maker.
I can't articulate what I find deal breaking in these tools. I would love to see more contenders to jira. From my understanding people generally hate jira for its ocean of configuration and slowness. Would love to learn more what problem jira is not solving, and would love to try more alternative. I have used github issues, basecamp, trello, among others for project management. They are all okay. At the same time definitely not miles better than jira. In my case, project management is something has to be there, doesn't matter which tool to use (given that most of okay).
Think of it this way.
An organization has 5 weird workflow issues that they can somehow shoehorn into Jira. Trello does 4 of them better, but doesn't do the last one; Github issues does 3 of them better than Jira but does two of them in an opinionated way that differs from the company expected workflow. Etc. So, the other options are disqualified because they don't handle all the requirements and often eventually only Jira remains as an option.
Random things I've seen (not all in the same place) as a must-have requirements for a project management system:
* doing cost allocation between departments for time spent on tickets.
* doing cost allocation between departments for time spent on tickets subject to a weird set of criteria that no sane product would include out of the box.
* integration of user roles, permissions and attributes (e.g. what's being billed) from whatever is configured in company Active Directory.
* track time allocation of people in teams distributed in an organization, disqualifying any solution that won't integrate all the people in a multinational company and all the projects in which a particular person might spend their time.
* having automated CI/CD deployment be contingent on actions taken on that ticket.
* having automated CI/CD deployment be restricted to actions taken on that ticket following a very specific set of rules who can approve what and what needs to be reviewed. etc.
As you can see, these aren't really "project management" features but aspects adjacent to it, but those are things required from a project tracking system in larger companies.
In essence, it's not sufficient for a product to provide a feature in one way; the key requirement is to have a product that can have software support for your particular way of doing that business process; and a solution must fit all the boxes, because the company won't use one tool for half of the process and a different solution for other half - well, not unless the data is magically synchronized, which is a very very hard thing to do properly.
An organization has 5 weird workflow issues that they can somehow shoehorn into Jira. Trello does 4 of them better, but doesn't do the last one; Github issues does 3 of them better than Jira but does two of them in an opinionated way that differs from the company expected workflow. Etc. So, the other options are disqualified because they don't handle all the requirements and often eventually only Jira remains as an option.
Random things I've seen (not all in the same place) as a must-have requirements for a project management system:
* doing cost allocation between departments for time spent on tickets.
* doing cost allocation between departments for time spent on tickets subject to a weird set of criteria that no sane product would include out of the box.
* integration of user roles, permissions and attributes (e.g. what's being billed) from whatever is configured in company Active Directory.
* track time allocation of people in teams distributed in an organization, disqualifying any solution that won't integrate all the people in a multinational company and all the projects in which a particular person might spend their time.
* having automated CI/CD deployment be contingent on actions taken on that ticket.
* having automated CI/CD deployment be restricted to actions taken on that ticket following a very specific set of rules who can approve what and what needs to be reviewed. etc.
As you can see, these aren't really "project management" features but aspects adjacent to it, but those are things required from a project tracking system in larger companies.
In essence, it's not sufficient for a product to provide a feature in one way; the key requirement is to have a product that can have software support for your particular way of doing that business process; and a solution must fit all the boxes, because the company won't use one tool for half of the process and a different solution for other half - well, not unless the data is magically synchronized, which is a very very hard thing to do properly.
Given these points (and point #2 in particular), I'm certain that project management using Google Drive + Google Sheets + Google Docs (or whatever cloud based office tooling you prefer) would be far more productive and cost effective than what Atlassian is selling.
I deleted my original comment, because I realized after the fact that you specifically cited "project management".
I'd just say it depends on the size of your org. Depending on what the projects you're trying to manage look like, the Atlassian tools offer some features that _really_ help. Prior to adopting Jira, teams were using some combination of Trello and Asana. The lack of any shared structure between teams made cross-cutting projects very hard to reason about.
Jira definitely has warts and annoyances, but it has a solid API and the JQL language for querying issue data is incredibly useful.
I'd just say it depends on the size of your org. Depending on what the projects you're trying to manage look like, the Atlassian tools offer some features that _really_ help. Prior to adopting Jira, teams were using some combination of Trello and Asana. The lack of any shared structure between teams made cross-cutting projects very hard to reason about.
Jira definitely has warts and annoyances, but it has a solid API and the JQL language for querying issue data is incredibly useful.
You'd think so, but people and especially enterprise devs seem to discount GDocs as viable and themselves gravitate towards Atlassian. I've dropped enterprise web project mgt tools for my team's in the past and the amount of hate I experienced for going back to Excel and weekly status chats (where I fill in the Excel for them) is astounding, and yet Jira is rarely updated truthfully. Maybe that's why they do it, Jira is a great place to hide lack of progress without embarassment.
[deleted]
Hard disagree, particularly when non-technical people are involved. Most I've worked with are awful at organizing, labeling, and just generally managing large amounts of data scattered across a bunch of files (something we do daily as software developers, so understandable), and giving them flexibility and freedom in organization will result in a shit show
This post makes some salient points about the challenges of team knowledge sharing:
- Tree structure is too strict for cross departmental content ex sales to customer success handoff - should that be under sales or customer success?
- The right answer can be found in multiple tools - companies are not going to ditch Google Sheets / Excel for Notion tables
- 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
- Collaboration needs to be as good as Google Docs or else people will just use Google Docs
It looks like the author is envisioning a new solution with Dokkument but if you want an existing one, take a look at https://slab.com. 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.
Disclosure: I am a co-founder of Slab
- Tree structure is too strict for cross departmental content ex sales to customer success handoff - should that be under sales or customer success?
- The right answer can be found in multiple tools - companies are not going to ditch Google Sheets / Excel for Notion tables
- 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
- Collaboration needs to be as good as Google Docs or else people will just use Google Docs
It looks like the author is envisioning a new solution with Dokkument but if you want an existing one, take a look at https://slab.com. 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.
Disclosure: I am a co-founder of Slab
Some friendly criticism. I was curious how slab topics work but could not find the details after a minute of trying to click and scroll around. The marketing bit about topics does not link anywhere. I finally made some progress by scrolling to the bottom, going to the support section, and searching for "topic". I had to scroll past results that described how to reorganize topics, assign permissions, until I arrived at the basics of topic usage. Even that did not provide an insight about how topics are different from regular tags, and I still am not sure what the difference is. So a "features" or "concepts" page would be nice, and even better if it was the main page. (I am an engineer.)
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!)
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.
"The content revolution hasn't happened yet!" [1] :-)
[1] with apologies to Alan Kay, https://www.youtube.com/watch?v=aYT2se94eU0
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.
"The content revolution hasn't happened yet!" [1] :-)
[1] with apologies to Alan Kay, https://www.youtube.com/watch?v=aYT2se94eU0
I should add Mathematica (obligatory emphasis), Sage, Jupyter, and other notebook-centric tools to the group of systems which tease the promise of a more "alive" computing model.
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).
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.
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.
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.)
Engineering managers think it's like this: Databases (good) > Documents (bad), and they get paid by the metric. And that's the good managers. The bad managers hate changing anything and want to stay with documents.
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 no idea just how bad the situation is, and have no desire to improve their consistency or internal organization.
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.
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.)
Engineering managers think it's like this: Databases (good) > Documents (bad), and they get paid by the metric. And that's the good managers. The bad managers hate changing anything and want to stay with documents.
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 no idea just how bad the situation is, and have no desire to improve their consistency or internal organization.
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.
Oh, good, you mentioned DOORS. It boggles the mind what it is that thing brings to the table.
I have a really hard time convincing anyone that they could have a specific, enumerable, sortable list of technical requirements, and that this is, on the whole, a good thing. Most conversions to DOORS I've heard of, though, basically were people taking ludicrously unorganized requirement documents and the heaps of hacky workarounds used to verify those documents, dumping it all into DOORS and Jira, and then saying that their resulting failure is the fault of DOORS and Jira.
DOORS is objectively shit. It was pure torturous software to use.
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.
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.
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.
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.
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.
OP here.
>I generally find these sort of diatribes against the market leading project management tools a little pointless.
Confluence and Notion are not project management software. But if you replace with knowledge base I agree with you.
At the end of the day the only things that matter is not the idea, it's the execution, and that's also the reason why we often end up with shitty tools.
We are trying something, if it clicks as you said, it clicks, if it doesn't it will be just another among the other ones
>I generally find these sort of diatribes against the market leading project management tools a little pointless.
Confluence and Notion are not project management software. But if you replace with knowledge base I agree with you.
At the end of the day the only things that matter is not the idea, it's the execution, and that's also the reason why we often end up with shitty tools.
We are trying something, if it clicks as you said, it clicks, if it doesn't it will be just another among the other ones
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.
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 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).
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).
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.
Jira...I can definitely see why people have issues. But confluence has always been rock solid for me and easy to use.
Jira...I can definitely see why people have issues. But confluence has always been rock solid for me and easy to use.
So uh, does anyone have a technical customer-facing knowledge base they like?
Getoutline.com is a great lightweight open source alternative to Notion.
Thanks for the link, how is it on mobile?
While it is open-source, it doesn't really look self-hostable: https://github.com/outline/outline/issues/1881
Depending on what you mean (e.g. without tweaking), it is actually possible to self-host. The thread you shared has comments that say they were successful.
Things I would like to see in a knowledge base:
* built in document aging and asset maintenance strategies - ideally including a time estimate for billing. A document not worth maintaining is not worth having.
* 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
* 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.
* graph and Venn diagram representations of viewer/authors and tags/topics, metadata, etc with killer app search and browse capabilities. Eliminate hierarchies, embrace dependencies
* built in document aging and asset maintenance strategies - ideally including a time estimate for billing. A document not worth maintaining is not worth having.
* 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
* 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.
* 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.
Exactly what is made for tech teams? All I see is generic features in there.
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.
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?
It didn't seem that way to me when I started building archbee.io — it's truly made for tech people.
Exactly what is made for tech teams? All I see is generic features in there.
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.
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?
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.
Agreed on these thoughts on ad-hoc taxonomies. The first Confluence page any team should create is their Taxonomy plan, with what goes where. Additionally, when creating a taxonomy you need to think of the "WHO" are the documents for. Some teams have docs for internal vs external stakeholders. The tone of those docs would be different. (external in this case are still people internal to the company, but on different teams.)
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: https://www.youtube.com/watch?v=EnB8GtPuauw
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.
If search and autosave worked well in Confluence, it would be fine.
Make it then. Nobody is obligated to create your perfect tool for you.
Just use emacs.
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.
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.
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.
Exactly, whenever I join a new team or a company I go to read the docs, and then whenever I bring some questions people say "oh, that's outdated, none of it is relevant anymore".
Technology can support the efforts to keep docs updated, but as you say, organizations must recognize this as an important part of work and make sure that people take care of the docs.
Technology can support the efforts to keep docs updated, but as you say, organizations must recognize this as an important part of work and make sure that people take care of the docs.
In those instances, were the docs useful as a starting point or historical snapshot? Or would it have been better not to have wasted your time with them at all?
IMHO the best way to tackle this for technical documentation is to keep it close to the code. It will then share the same lifecycle (code update without corresponding docs update shouldn't happen and should be enforced via reviews) and has a higher chance of staying up to date.
Guru does this. Full disclosure I work for Guru. It's pretty interesting working for a knowledge management company and seeing this topic on the front page, then reading the comments describing exactly what we are working on.
I'd argue that there's far too much documentation for documentation sake... nobody wants to spend valuable time updating a document that nobody looks at.
we all say this, and then we get annoyed because we’ve finally found a moment away from meetings to do our preferred work task, only to have a certain chunk of our valuable time being spent explaining something which could easily have its own document. then we rinse and repeat.
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.
To paraphrase Thomas Sowell: "The least productive people are usually the ones who are most in favor of [using Atlassian products]".
To paraphrase Thomas Sowell: "The least productive people are usually the ones who are most in favor of [using Atlassian products]".
I think this is overly simplistic, and extremely naivive speaking as a manager. You sound like someone who's a year out of college (or suffering from some other immature personality characteristics) and/or working for a company with very few employees.
I routinely orchestrate tech delivery between anywhere from 3 to 10 dev teams across our organization. I'm totally open for suggestions on better tooling that: a) don't require me to schedule a ton of meetings instead to get status on all the various teams dependencies, dragging everyone into meeting hell b) don't require me to use multiple tooling for different teams c) don't require me to make project plans in other legacy tools like Microsoft Project, or even the newer "spreadsheet" tools like Smartsheet or Airtable, etc...
EDIT: Some other features I use all the time (speaking mostly in JIRA land): 1) one click linking from the JIRA issue to the Github PR 2) Partitioned Kanban/Sprint boards for each team, as well as easy ability to rollup to master board for entire project 3) Ability to Search, advanced search, filtering, custom dashboarding, etc. 4) Array of plugins to work with other tools like Slack (I can one-click create JIRA tickts from slack conversations), and I can additionally run JIRA queries and bring in the results into my EMACS workflow. 5) I won't go into all the bigger company things like user management, integration with SSO providers, etc, since that doesn't impact me and my team(s)...
In short-every one has their use cases. And orgs of various sizes will have their own.
I routinely orchestrate tech delivery between anywhere from 3 to 10 dev teams across our organization. I'm totally open for suggestions on better tooling that: a) don't require me to schedule a ton of meetings instead to get status on all the various teams dependencies, dragging everyone into meeting hell b) don't require me to use multiple tooling for different teams c) don't require me to make project plans in other legacy tools like Microsoft Project, or even the newer "spreadsheet" tools like Smartsheet or Airtable, etc...
EDIT: Some other features I use all the time (speaking mostly in JIRA land): 1) one click linking from the JIRA issue to the Github PR 2) Partitioned Kanban/Sprint boards for each team, as well as easy ability to rollup to master board for entire project 3) Ability to Search, advanced search, filtering, custom dashboarding, etc. 4) Array of plugins to work with other tools like Slack (I can one-click create JIRA tickts from slack conversations), and I can additionally run JIRA queries and bring in the results into my EMACS workflow. 5) I won't go into all the bigger company things like user management, integration with SSO providers, etc, since that doesn't impact me and my team(s)...
In short-every one has their use cases. And orgs of various sizes will have their own.
Ask yourself if any of the things you mentioned actually result in a materially significant improvement in delivery of working software, in comparison to say... sticky notes and sharpies.
I think it's incredibly obvious that just about any tool that can used remotely will be orders of magnitude more effective and helpful than sticky notes.
You start with sticky notes and a whiteboard, and then you note that nobody remote can change the whiteboard unless somebody else does it for them. And when you work from home, you can't see the updates unless someone sends you a photo. And Ralf's handwriting is terrible.
So you look for something that replicates the whiteboard on the web, and it's either too freeform or too rigid or too expensive...
So you look for something that replicates the whiteboard on the web, and it's either too freeform or too rigid or too expensive...
Sorry, can't resist: you've perfectly teed-up ShareTheBoard. Solves the exact problems you've listed here. https://sharetheboard.com
When I was using it i quite liked it. Speed was not great, but custom workflows for Jira worked nicely and confluence was fine.
I actually quite like Jira and Confluence. They are the pure distillation of garbage in, garbage out, though.
We've kept them because they link well and through to GitHub, and you can generate decent regulatory documentation through querying Jira, which we need to do.
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.
Yes, it could be better, but I am happy that it is not a lot worse.