Confluence is broken. Here’s how I plan to fix it.

Francesco Lanciana
Nov 11, 2019 · 4 min read
Image for post
Image for post

Confluence, along with all current documentation tools, don’t scale with your team.

You start out with one or two people and only a few documents. At this point information is easy to find and things are going great. But then time passes and your team grows, now you have a few more documents. You can still find what you need, but it can take a while plus you notice that more and more of your documentation is becoming outdated. Still no need to panic, just make Greg work overtime, Greg loves working overtime…

More time passes, your internal wiki is getting pretty sizeable. You start needing to ask your team mates which document contains the info you need. New documents are being published every day but you aren’t sure which ones you need to be across. When you occasionally muster up the motivation to write down some of the info stowed away in your head you have no idea if anyone even read it. Not only that there is now a Greg shaped hole in the wall and the amount of times you have referenced outdated documentation is astounding. Things are looking pretty grim…

At this point documentation becomes viewed as a time sink and people start to prefer other practices like pairing with a team mate, comprehensive user stories and code tests. These unfortunately are only a bandaid solution to the problem, tending to put the onus back on the already time pressured staff to train people one by one. They should absolutely still be done, however they shouldn’t replace having and maintaining a top notch knowledge base.

Fear not, good people! It really doesn’t have to be this way, Greg deserves better! I’ve started developing a new tool focused on teams that aims to solve the following problems (just a list, not in any particular order of importance):

  1. Discoverability of documentation is very poor (woeful for the unknown unknowns)
  2. Most products don’t encourage interaction and collaboration
  3. Most products don’t give you insight into how people interact with your document.
  4. Documentation constantly becomes outdated.
  5. Documentation takes a while to write, why not allow for more free form content to document fast changing parts of your organisation?

Its name is Scribe. To combat discoverability of documentation it will introduce the ability to make teams on the fly, where team members can publish to and organize their teams feed. Interaction and collaboration is a broad one, but features like the ability to react (clap) to documents, comment on any part of a document, and add resources to a document that you found helpful (even when you aren’t the author) are some of what will be incorporated to address it. A document level and wiki level analytics section will give you insight into how people are interacting with content. This will go a long way to showing you knowledge gaps in your organisation as well as how to improve each document. A If-This-Then-That feature called Scribes will give you the power to bring documents to life. For example If This code file changes Then mark this document as outdated. I’ll expand on the last point down the line, honestly that was a very recent thought of mine.

Here are some juicy screenshots to tie you over until it is brought into existence with blood, sweat, tears, and a 3x3m plank of an old old wooden ship.

Image for post
Image for post
A B-E-A-utiful editor that encourages third party interactions
Image for post
Image for post
Analytics on every document so you can finally quantify how amazing your documentation really is

I have a lot of ideas when it comes to making documentation useful and dare I say it enjoyable. Personally, I think integrations are overdone, how many times do you actually use them? I don’t think 99.999% of people need an editor so powerful each document becomes an app in and of itself. Because you love hearing my opinions, hears one more. I think documentation tools are really missing the ability to have quick free-form answers to questions your team mates have. The things you are documenting can change rapidly and documentation isn’t exactly the quickest thing to write. Save the formal documentation for the slower moving content that a lot of people need to be across.

I truly believe documentation can be a massive force multiplier if it’s done right. Unfortunately Confluence and Co. haven’t shown me they are up to the challenge of making that a reality so I’m taking things into my own hands.

If what I have written resonates with you please please please get in touch or leave a comment, I want to hear about your experience. If you have ideas for a documentation tool that I haven’t touched on let me know, if they are good I will give you a year subscription for free. Lastly let me know if you would like to hear more about my epic quest to make this a reality, I’m open to more blog posts or perhaps even a vlog (the world definitely doesn’t have enough vlogs haha).

Lastly lastly make sure to check out the landing page and sign up for beta access if you like what you see!

The Startup

Medium's largest active publication, followed by +771K people. Follow to join our community.

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store