> The solution we had was to give one Space for each team/department in the company
This is the single biggest tip I would give any company who uses Confluence. For some reason, most companies I work for that use Confluence insist on using minimal separation of Spaces. I.e. IT in general has a Space, and my team has a folder nested 6 folders deep in some path that I can never remember and have to bookmark.
It makes search effectively useless. If I search for "X api documentation" I get 10,000 results ranging from meeting minutes that some unrelated team put up that just happen to use those terms, to pages from other teams documenting how they use the API.
A Space should be treated the same as a Jira project. If I had my way, I would create a Space every time we created a Jira project.
And my biggest request for the Confluence team would be better markdown support (I should be able to indicate that I want to type Markdown without having to click through a giant list), and a way to set up a space to sync from Markdown files stored in Git. Some of us don't want to use the WYSIWYG editor, and I would love to be able to use an MR review process for documentation changes before they go live.
From Steve Yegge's famous Rant about Google not understanding platforms:
So one day Jeff Bezos issued a mandate. He's doing
that all the time, of course, and people scramble like
ants being pounded with a rubber mallet whenever it
happens. But on one occasion -- back around 2002 I
think, plus or minus a year -- he issued a mandate that
was so out there, so huge and eye-bulgingly ponderous,
that it made all of his other mandates look like
unsolicited peer bonuses.
His Big Mandate went something along these lines:
All teams will henceforth expose their data and
functionality through service interfaces.
Teams must communicate with each other through these
interfaces.
There will be no other form of interprocess
communication allowed: no direct linking, no direct
reads of another team's data store, no shared-memory
model, no back-doors whatsoever. The only communication
allowed is via service interface calls over the
network.
It doesn't matter what technology they use. HTTP,
Corba, Pubsub, custom protocols -- doesn't matter.
Bezos doesn't care.
All service interfaces, without exception, must be
designed from the ground up to be externalizable.
That is to say, the team must plan and design to be
able to expose the interface to developers in the
outside world. No exceptions.
Anyone who doesn't do this will be fired.
Thank you; have a nice day!
I think about that a lot when designing any system, machine- or human-centered, that needs to communicate with a disparate group of entities. Encapsulate the implementation details to those who are closest to the actual information and have enough power to take action, and make the contact interfaces very explicit. This alone will get you 85% of a functional system. The rest is just selecting actors in your system that know how to cooperate and understands these boundaries.
This is the single biggest tip I would give any company who uses Confluence. For some reason, most companies I work for that use Confluence insist on using minimal separation of Spaces. I.e. IT in general has a Space, and my team has a folder nested 6 folders deep in some path that I can never remember and have to bookmark.
It makes search effectively useless. If I search for "X api documentation" I get 10,000 results ranging from meeting minutes that some unrelated team put up that just happen to use those terms, to pages from other teams documenting how they use the API.
A Space should be treated the same as a Jira project. If I had my way, I would create a Space every time we created a Jira project.
And my biggest request for the Confluence team would be better markdown support (I should be able to indicate that I want to type Markdown without having to click through a giant list), and a way to set up a space to sync from Markdown files stored in Git. Some of us don't want to use the WYSIWYG editor, and I would love to be able to use an MR review process for documentation changes before they go live.