Confluence is broken. Here's how I plan to fix it
medium.com
medium.com
So if Confluence and internal knowledge sharing is problem for your team but you want to try out a ready and available product, please give https://slab.com a look.
#1 Explicit Document ownership. The primary author, as well as team distro list slapped at the top.
#2 Document aging. If a doc goes over X days without review by the author or team, it is listed at the top in yellow/red/etc as some level of "Stale" so others know. This also has the slight shame effect if you're the primary owner and all of your docs are bright red and stale.
#3. Directory structure template that you enforce on your entire org. So when a new team starts, you can have some sort of standardization stamped out around where things are like Design Docs, Runbooks, Meeting notes, etc, etc
Even if it just ends up being a trigger for people to go 'hey, I cbf updating this anymore' and deleting it. It's better than just keeping it around in limbo forever. Our confluence is a graveyard of useless pages and it's only going to get worse over time. I imagine most are the same.
As for #2 I fully 100% agree, I was going to work that into the Scribe feature (ability to have if-this-then-that actions) so you could say If this document is older than x days mark it as outdated for example.
I hadn't thought about #3 but I like it!
It's easy to build toy systems. My working definition of "complex systems" is "you've got to think before doing something". There are interactions, there are implications, there are consequences.
You can cobble together a small wiki of a handful, or even a few dozen, pages, with ease. As that collection scales, both in page count and page size, the ease of working with the compilation becomes a challenge.
The Unix / Linux world offer a touchpoint. Of documentation, there is source code, in-application help, manpages, alternative documentation (hello, texinfo, please go rethink your meaning for existence), collections such as the Linux Documentation Project (once a gem, now rare to find a HOWTO younger than a decade and a half), various distro wikis and documentation archives.
There is documentation which remains current and useful. The Debian project updates (and creates) manpages (and considers their lack a bug, though not a release-critical one), as well as a trove of its own docs (some now staling a bit, though much still admirably current). My view is that all documentation is a palimsest, and for utility if not archival, old velum must periodically be scraped clean and re-inked with new works.
Memory and memorialisation are themselves a denial of progress and time. This can be useful, certainly, but also handicapping.
Active projects, work teams, and organisational documentation suffer from the challenges of constant flux (project, goals, priorities, personnel), under-resourcing, often a failure of any participants, certainly most, of having an accurate (or mutually consistent) big-picture view. That moment at the end of an RSA Animate lecture where the camera pulls back from the whiteboard and suddenly the entire scope of a talk is presented as a single whole has its analogue in technological work.
As for metadata, I've just had a long (and profane) Mastodon discussion on that topic. Relevant bit begins about here: https://mastodon.social/@mathew/103116638919554591
Structuring of documentation is a whole 'nother religious war. For books which can only occupy a specific location on a shelf, that's essential. For files or documents within a CSM, various other groupings become more appropriate, and can be flexible, though a nominal "principle map" or route through the major elements of a corpus can certainly be useful. The bound codex provides both random access and explicit ordering of content, principles which are difficult to improve upon.
Online systems which can create on-demand standalone formats (PDF, ePub, HTML) can be a useful hybrid and/or emulation of this.
I'm still sad at the death of DekiWiki / Mindtouch -- it was one of the best wikis I ever used, but was abandoned around 2010. It offered a structured hierarchy, a decent editor, was performant, looked good, self-hosted, scriptable extensibility, etc.
I've never found a satisfactory replacement.
I do agree that getting Enterprises to buy into my tool over Confluence will be really difficult, and until then I'll struggle to help you, but I'm lining up as many talks with people that can make that call as possible to see what I would have to do to make that a reality. One thing you might find interesting is that I plan to make Scribe free for public wikis, so while it might take some time for your team to use it, it might be useful to you if you do open source work? And if you like it enough maybe you can recommend it to your team, who knows!
Refer the wayback machine, as Mindtouch took down their documentation a while ago. Short of running up a live copy [1] on a VMware instance, the fastest way to get an idea of the features is to review their user & API documentation [2].
The sourceforge site has some screenshots, but I suspect there are very few publicly accessible instances anymore, as the thing was so damned hard to patch (VM images were how they distributed the software). I did find this [3] but you won't get to experience editor / API, only the navigation.
Deki's hierarchy worked - most other products I looked at this was an effort (plugins, extensions, etc) - either way it prevented orphan pages, and reduced the risk of losing pages or people accidentally creating duplicates.
The hierarchy was also reflected in the URL, which is just lovely (compare Sharepoint). Confluence has a hierarchy, but the URL does weird things, and I think there's a global namespace for pages IIRC. Their URL's sometimes go a bit whacky, but haven't worked out why.
[1] https://sourceforge.net/projects/dekiwiki/
[2] https://web.archive.org/web/20120828154742/http://developer....
But the fact lots of people still have DC's, or host stuff on their office server, or don't want other organisations outages to be their outages, or be exposed to billing tomfoolery, easy integration with other internal systems without blowing myriad holes through their firewalls, (etc) means there's still a market for on-premises software.
> At this point documentation becomes viewed as a time sink and people start to prefer other practices like pairing, comprehensive user stories and tests. These unfortunately are only a bandaid solution to the problem...
I think that "pairing, comprehensive user stories, and tests" are all good things you should have anyway, and documentation can't be a replacement for them.
[1] https://en.wikipedia.org/wiki/Pair_programming
Pairing - Pair programming, which if one of the developers has experience with the product will solve questions that you otherwise will solve with docs.
Comprehensive User Stories - User story like in Agile/Scrum, where it has an acceptance criteria, goals, description, etc. and can be used to track back documentation of features.
Tests - User test cases, which can be a replacement of the documentation of how to use the product or the intent of the features.
edit of a new page/section is a PR to the repo. once merged, you can auto deploy it to the target destination, rendering via jekyll or mkdocs or other things.
Discussions happen in PRs in that model. (you can also added previews of the PRs and deploy these next to the production version of the site)
Markdown has lots of variants but is ok to wrangle most of time and pandoc handles it very well. Github renders it natively.
Emacs org mode is awesome and github renders it native but when not everyone is using emacs or a tool with org-mode plugins it it can cause issues when others try to access/edit it when using some of the more advanced features, so I use it for personal use and as a data science notebook. It replaces Jupyter notebook for me.
Asciidoc and Asciidoctor are currently the particular implimentation of markdown that is working towards a defined spec (https://asciidoctor.org/news/2019/01/07/asciidoc-spec-propos...) that I am leaning into the most. They are the best of both worlds. I am planning on moving my websites to asciidoc instead of org mode.
Documentation from code and code comments is much more specific and so I would say outside discussion scope.
I think that a markdown with a more well thought out spec such as asciidoc(tor) are working towards is going to be the future, and I think that the wysiwyg tools themselves are the main pain point and are what need to be worked on the most.
In the past when I have had to deal with confluence I have just asked confluence admins if we can use the github or html frames plugins so I can do documentation independent of confluence itself.
We like Git (alongside the code) for docs that are tightly coupled to the API, and Confluence / Google Docs for more general or high-level descriptions, design discussions, operational procedures, etc.
Discoverability is hard. Build a better mechanism for that and you could set your sights higher than a better wiki.
I can't understand how the rest of the enumerated points is a problem with wikis per se. Or what the numbers assigned to those points mean, for that matter? (Ranking? Reference? Decoration?)
As for discoverability you are right, it's definitely hard. My idea here is to allow people to create teams on the fly. You then have a feed that your team members and manager can push content to and manage.
Oh the numbers didn't mean anything, I was just trying to make it easier to read. Will see if I can reword it to make it clearer :)
As for them not being a problem with wikis, I think they are if you look at the wiki as not just being a collection of documents but as being a living breathing knowledge base. Interaction and collaboration are important to encourage if you want people to feel like their documents are actually being used. Even a simple clap button like Medium has would go a long way in this department. Insights into how your document is used would help show you how to refine the document, and also feeds into your work being valued. Plus it might really help managers gain a better understanding of the knowledge gaps that exist. Documentation becoming outdated is a reality that I feel most tools out there ignore, but addressing it is really important in having people trust what they read (I know my trust in my teams documents dropped off pretty rapidly after I kept finding them to be outdated). The last point was more of a thought I had two hours ago haha, and again really ties into having a living breathing knowledge base people can trust and want to use.
Much like JIRA, Confluence is incredibly powerful but effectively requires a full-time person taking care of it and organizing/cleaning things up. Unfortunately the scale at which Confluence breaks due to the number of documents and lack of organization is far lower to the scale that would warrant such a 'caretaker' role hence I've never seen Confluence used in a fashion that didn't get in everyone's way and exhibit all issues the article listed.
However, I find that nuggets are often embedded in subsections of larger documents.
Perhaps the search could rank higher a document with subsection with query words in the title. (Maybe they do in some tools?) Any set of query words could be by chance present, but scattered in a hundred large documents not relevant for the user. Conversely the tiny specific subsection I’m looking for is lost in the noise.
This very thing happened when I was looking for the delivery and address information for a main office. Huge number of documents mentioning address of something and delivery of something showed up. I even remebered seeing an earlier revision of the subsection I was looking for, but it didn’t help. IIRC even adding parts of the street address didn’t help because the plain address was common in many documents for random reasons.
Personally I also like to divide my technical documents into subsections with exact titles. It would be great if tools knew how to exploit this kind of hierarchy.
However, I don't really understand how your product integrates with or improves Confluence?
I don't see any point in reading an article stating something that is untrue, in this case Confluence which if it was broken would not have hundreds of thousands daily users nor a developer raking in cash from new licenses.
If you want my interest or click, say "How to make Confluence 2x better", "A better alternative to Confluence" and so on.
Because if you want me to invest in you or your product, don't start by lying to me. It'll only makes me question what else you are not honest about.
This is just engaging in the conversation in bad faith...
It's a way smaller chance that I'll click a link or read an article if it starts off with something that is wrong, instead being clear and precise in your communication is IMO a huge advantage when trying to attract me as a customer.