Normally I would not promote my own company to the HN community without contributing something of value, but from the looks of the UI decisions in the "juicy screenshots" I would venture to say we have already done so: https://share.slab.com/v1uy96K8
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.
Cheeky, but all is fair in business I guess. I had a look at every product I could possibly find (Notion, Confluence, Slab, Bear, CodeStoryApp, Evernote, Dropbox Paper, Google Docs, GitHub Wiki, Quip, Guru, Slite, Coda... listing them out makes me anxious) and made sure to incorporate what I thought were really smart product decisions. From Slab I really liked the table of contents and having the search bar up the top left, I can't say much more was included in Scribe that doesn't exist in every other product tackling this space though.
#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
I really like the idea of #2. Maybe combined with some way to indicate the 'lifespan' of a piece of documentation at the time of creation. We've got bits of docs lying around that were intended to be updated weekly, and regularly fall to the wayside for months at a time. A way to just tag them as 'weekly' and have them pop to the top of a list in yellow/red when they haven't been updated in 7/10 days, would be useful.
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.
I'm glad to hear I wasn't the only one experiencing this. When using the Scribe feature I mentioned to mdeeks if anything becomes outdated that was under your purview you will see it at the top of your feed. Didn't want to go down the notification route because I was worried you would get 100 notifications and just learn to ignore them
These are really great suggestions! I have been thinking a bit about ownership and accountability. The author thing is a good idea. Currently I was thinking that when you hover over a given block (e.g. paragraph, table, ect) you would see icons on who created and edited it so you would know who to ask if something wasn't clear.
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.
Automatic aging is a good suggestion, though some mechanism for manual review / rating (and, probably, aging of that) could also be quite useful.
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.
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.
Confluence is objectively horrible, without a doubt, but adding (yet) another candidate to the marketplace isn't really fixing Confluence. For starters, I'm still going to be stuck using Confluence.
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.
Maybe "Here's how I plan to rectify it" would have worked better... putting that aside you Jedd are in luck! Scribe isn't just any candidate, it's the candidate (If I can get enough people to throw money at me so I don't have to go get another job). I'll have a look at DekiWiki and Mindtouch tonight. What did they offer in terms of structured hierarchy that other tools don't? Also interested to see what this scriptable extensibility is.
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.
Absolutely, so long as you mean 'in the alleged era of' rather than 'in the market of', of course.
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.
Cool app. I agree with your points about Confluence's issues.
> 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.
Can someone explain what "pairing, comprehensive user stories, and tests" are? Are these actual terms or is the author just talking about teammates getting together to work on an issue?
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.
Sorry, that could have been clearer. I meant the practice of pair programming, including user stories in Jira tickets (to explain why the ticket exists in the first place) and tests for your codebase to help others understand how the code operates.
It depends. An edit button with a WYSIWYG flow is much more conducive to casual fixes/updates than a fork -> clone -> edit -> build -> code review -> land workflow. But in-repo docs are easier to keep in sync with the code 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.
Markdown type documents in a vcs are the best documentation system in my opinion. The problem really shows up when you are then trying to get non-technical users to participate, hence the abomination of wysiwyg web editors such as confluences (which is indeed broken, especially without plugins).
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.
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)
It is wiki nature to be an ephemeral snapshot of documentation in time. To ask it to be otherwise is like asking "a minute ago" to always be up to date.
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?)
I agree that a wiki will never be truly up to date, however I do think it's possible to build in mechanisms that tell people what is and isn't up to date. For example if a code snippet you include in your document changes (i.e. it's updated in GitHub) then the document should be either marked as outdated or in need of review.
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.
Confluence is broken and almost all the solutions that have been provided here is broken since they are not open source. They don't let you contribute and you have no open way of suggesting and/or coming up with another feature. Wikis are not WYSISWYG, some of the platforms our there are SaaS and you can't trust them fully to store your company wide data and this list goes on. This is why (shameless plug) we develop Balsa in an open manner to fix how we document things. Check https://github.com/balsa-team/balsa and start contributing.
I'm excitedly waiting for Clubhouse Write as I couldn't get into the private beta but if it does as good a job at replacing Confluence as Clubhouse did at replacing JIRA for me then I'll be shouting it from the rooftops.
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.
Oh good another competitor haha. I really like the way you worded the scaling issue, couldn't agree more. When I release it I'm hoping you're still in a shouting mood.
Not the original commenter, but he got me thinking. (I’d like to know what he soecifically meant too.)
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.
I don't think I understand. You say you're going to fix Confluence. That's great! Lots of us are stuck using Confluence, after all, and it has many deficiencies.
However, I don't really understand how your product integrates with or improves Confluence?
I am quickly learning I need to spend more time wording things appropriately haha. To be clear it doesn't integrate with Confluence in any way, shape or form. Scribe is really a direct competitor to Confluence. But it will fix all the deficiencies that Confluence has.
I don't think I understand how Confluence (an awesome tool) is flawed and how adding a page view counter to a wiki is going to fix all the "problems" listed
Hey could you give it another read? I've added a bunch more detail about what the product actually does to try and tackle these problems. Thanks for the feedback, I somehow completely overlooked the fact I didn't tell you what it did haha
Dear Franceso and others,
please stop writing "X is broken" when it is clearly not.
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.
As a Confluence user (not by choice) I must disagree, it's broken in several ways. The one I'm most frustrated by is their search -- we've got an internal page titled "Fizzbar 8" which does not appear in searches for "Fizzbar 8" despite also containing that string multiple times in the body text.
Market success doesn't mean something doesn't have serious problems. It could mean a great sales team, or a successful strategy like pitching at key decision makers and have little to do with the quality of the product. I've used Confluence, and I personally hate it. I imagine many find themselves in the same situation. I don't get any choice, except find a new company to work for.
Valid point, I've probably been reading a bit too much marketing focused material, figured the title would get more attention (which to be fair it did get you to comment). However I really do believe that tools like Confluence become terrible user experiences as your team grows. The wiki quickly becomes a black hole, documentation becomes hard to find, you have no idea if anyone read or found your content useful and outdated documentation becomes the norm. You could attribute this to the team or the company culture but I think it's more to do with the tool not giving you the primitives you need to do the job well.
Oh come on, don't get caught up in the word games, it's unproductive. You know the author meant something more specific than "X is broken" because he wrote an entire article explaining what he means when he says "broken".
This is just engaging in the conversation in bad faith...
I understand what you are saying but my intentions are good and I'm trying to help.
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.
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.