We deserve better than Confluence and Notion(blog.luap.info) |
We deserve better than Confluence and Notion(blog.luap.info) |
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.
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.
To paraphrase Thomas Sowell: "The least productive people are usually the ones who are most in favor of [using Atlassian products]".
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.
So you look for something that replicates the whiteboard on the web, and it's either too freeform or too rigid or too expensive...
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.
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.
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.
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 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.
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).
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 ).
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.
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.
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.
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.
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...
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.
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.
We have those, we call it filesystem or fileserver.
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).
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)
- 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
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
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.
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.
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.
>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 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?
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).
Jira...I can definitely see why people have issues. But confluence has always been rock solid for me and easy to use.
* 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
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.
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 imagine if a company using Trello wants more features they probably just say “use Jira”.
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.
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.
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.
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.
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.
(Context: https://onemansblog.com/2010/05/18/prison-joke/ )
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.
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
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).
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.
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.
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.
Comically, SharePoint makes me tolerate Confluence and Salesforce more.
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).
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.
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").
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".