I've lately been working on a Confluence documentation pipeline at my work that creates/updates Confluence pages from an external data source. However, we'd like to close the loop and allow people to be able to update those pages (or add new ones) in Confluence and scrape the data back out.
The reason we're taking this approach to documentation creation:
My discussion topic here is fairly open ended, but boils down to a few key questions:
While I'm all for the one source of truth and a big advocate of it at work, for at least some of the documentation I'm talking about it'd be more convenient for the end user to have their cake and eat it too. I'm more interested in the thought experiment of how one might approach it.
Take a glossary for example that has a separate page for each entry--in this case, we'd benefit from the ability to have a consistent template across all entries, so that leads us down an avenue of having to update the display of the data from some external source. However, it's counterintuitive for users to think, "Oh, I'll add an entry to our documentation glossary! Wait... I have to go to another tool do that?" I'd like them to be able to add entries piecemeal to the glossary, but also be able to update all entries as necessary when people want to organize the information in a different way.
At first I was thinking a macro that pulled from an external data source might be a way forward. Just specify such and such ID that corresponds to such and such datasource and the information magically appears. However, that data isn't very searchable since all that is input onto the page is the macro call and the source data ID.
I do wish that Confluence had some kind of form (maybe there is?) so that when a user enters edit mode on certain pages, the user can only input data in certain fields, but we take care of the formatting on our end. That screams macro to me, and maybe the answer is to use macros, but input more data into them.
I certainly recognize the problem of keeping data up to date. One simple rule is key in my perspective: there is only one point of thruth! Only one place is the real source of information, the rest is derived from that point.
People tend to make their own list, own data collection. Go and talk with them, understand why they do it, understand how they like to be in control and provide a suitable way that works for that person.
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.