In the beginning, there was READMEs and code comments, and the great architect in the sky saw that it was good.
As software grew, so too did the tomes accompanying it, and tools were developed to help manage it. Sharepoint, wikis, and automated documentation build processes. But they were all deceived, in the darkness of Sydney, a tool was forged by the dark master Atlassian, and thus unleashed on the world was Confluence.
I have a love-hate relationship with documentation. I believe there is a necessary level of bureaucracy required to properly control releases, help with code maintenance, and capture design decisions. However, there are people that base their whole careers around “managing” tools such as Confluence, and will often insist that EVERYTHING be noted in a Confluence article.
The end result of this is an unnavigable mess. The search function doesn’t work, I’ve searched for titles of articles I created the day before and instead get shown a jumble of unmaintained pages from 5 years prior. What used to be a simple markdown entry box has been replaced with a WYSIWYG editor that has eschewed any semblance of disgruntled programmer friendliness.
Do I think it could be a good tool? Sure. Atlassian has the resources to throw behind it, and I’m sure they run it in house in a sensible fashion. Why don’t they make it easier to do properly? Why were my power user features ripped out? Why can’t I find articles a second time, being forced to bookmark anything important in my browser?
Many questions to which I’m unlikely to get answers. I’ve known devs that have worked for Atlassian in various capacities, and all were excellent engineers, so I know that the problem doesn’t lie with the company’s hiring policies. Maybe there’s some short-sightedness on the feature roadmap or something.
Maybe we’re on the brink of another discovery in this field, what form that takes I don’t know but we need something better. Documentation is important, but so is being able to find it again.
Just a thought I wanted to jot down before I got distracted with other things. Maybe I’ll keep thinking about it and come up with an easier solution, because at this point markdown in my repos is still the best answer.