
Confluence is broken. Here's how I plan to fix it - francescol
https://medium.com/@francescolanciana/confluence-is-broken-heres-how-i-plan-to-fix-it-ffb736fd2b28
======
jhchen
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](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](https://slab.com) a look.

~~~
francescol
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.

------
mdeeks
I'd love for any of these tools to offer :

#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

~~~
BigJono
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.

~~~
francescol
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

------
Jedd
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.

I've never found a satisfactory replacement.

~~~
francescol
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!

~~~
Jedd
Hi Francesco - happy to reminisce.

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/](https://sourceforge.net/projects/dekiwiki/)

[2]
[https://web.archive.org/web/20120828154742/http://developer....](https://web.archive.org/web/20120828154742/http://developer.mindtouch.com/en/docs)

[3] [http://www.osslab.tw/](http://www.osslab.tw/)

------
mbil
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.

~~~
missingrib
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?

~~~
v64
I assume they mean pair programming [1], user stories which are used in agile
methodologies [2], and test-driven development [3].

[1]
[https://en.wikipedia.org/wiki/Pair_programming](https://en.wikipedia.org/wiki/Pair_programming)

[2]
[https://en.wikipedia.org/wiki/User_story](https://en.wikipedia.org/wiki/User_story)

[3] [https://en.wikipedia.org/wiki/Test-
driven_development](https://en.wikipedia.org/wiki/Test-driven_development)

------
charezinski
I worked with confluence, google docs and git like repos. Wholeheartedly
prefer the last one.

~~~
aerojoe23
Git like repo? Could you please elaborate?

~~~
je42
writing a lot of markdown docs. ;)

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)

~~~
je42
the better your git repo tool supports online editting the better this
experience will be.

------
drewcoo
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?)

~~~
francescol
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.

------
gorkemcetin
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](https://github.com/balsa-team/balsa) and start contributing.

------
somada141
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.

~~~
francescol
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.

------
fouc
Organizing at the document level is the main mistake that virtually all of
these tools make. Search doesn't get around that mistake either.

~~~
francescol
I'm really interested, what do you mean by that? How do you think they should
be organised?

~~~
Pelam
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.

------
randallsquared
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?

~~~
francescol
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.

------
stevebmark
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

~~~
francescol
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

------
francescol
To everyone that gave me your email, I appreciate it massively. Look forward
to some great (and I promise non-spammy) updates :)

------
TheChaplain
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.

~~~
diminoten
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...

~~~
TheChaplain
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.

