Mapping the Unknown, How Process Documentation Saved My Sanity (and Maybe My Job)

The Problem: A Black Box Wrapped in Red Tape

About a 15 months ago, I found myself in what I can only describe as a peculiar sort of professional purgatory. After spending the better part of two years learning React, building side projects, and convincing myself I was ready for that elusive developer role, I instead landed in a position managing Oracle WebCenter Portal and Content Server (UCM) - a platform whose internal processes had apparently been passed down through oral tradition like some sort of enterprise folklore.

No documentation. Fragmented ownership across multiple teams. A profile creation process that involved spreadsheets, a .NET team who didn’t want the work, and release cycles that could charitably be described as “glacial.”

The technical challenge wasn’t even the hard part - WebCenter is well-documented publicly. The impossible bit was understanding who does what, when, and why, and more importantly, how work managed to sit in queues for months whilst everyone pointed fingers at everyone else.

If you’ve ever inherited a legacy system where the original architects have long since moved on and the current “process” is whatever ad-hoc workaround the loudest person in the room insists upon, you’ll know exactly what I mean.

The Lightbulb Moment: You Can’t Fix What You Can’t See

I’m not naturally a “process person.” My background meanders through project management (risk registers were genuinely exciting for about six months), machine learning (random forests are still magical, even if I never got to use them professionally), Web3 (still not convinced it’s real), and lately, a pivot towards security and infrastructure. But one thing that’s consistent across all of those domains: you cannot improve what you cannot measure, and you cannot measure what you haven’t defined.

The turning point came during yet another meeting where someone asked, “Why is profile work taking three months?” and three different people gave three different answers. The Service Desk said it was the BAs. The BAs said it was the .NET team. The .NET team said, quite honestly, “We don’t want this work and it goes to the bottom of our queue.”

Fair enough, really.

I realised that before I could take ownership of profile builds (which was supposedly my job), I needed to understand the current state - warts and all. Not the intended process, not the ideal process, but the actual, messy, Byzantine reality of how requests flowed through the organisation.

Time to map this nightmare.

The Method: Collaborative Process Mapping (Or: How I Learned to Stop Worrying and Love the Flowchart)

I started with what I thought I knew:

1. Requests come in (somehow)
2. Service Desk creates an initial portal
3. Business Analysts build portals and handle profile spreadsheets
4. .NET team builds profiles (eventually)
5. DBAs deploy to production
6. …profit?

Turns out, I knew roughly 40% of the actual story, and most of what I knew was wrong.

Step 1: Interview Everyone (Separately)

I scheduled sessions with:

• Service Desk team: They handle tickets, user accounts, initial portal creation, and security groups
• Business Analysts: Requirements gathering, sizing, UAT, and apparently the only people who actually talk to customers
• Training Team: Wonderful people who ensure users know what they’re doing and occasionally hold the rest of us accountable
• DBA Team: The gatekeepers of production, and quite rightly cautious about what goes live
• .NET Team: Honest about not wanting profile work, which I respected immensely

I asked simple questions:

• “Walk me through what happens when you receive a [portal/profile/change] request.”
• “What do you do with it?”
• “Who do you hand it to next?”
• “What could go wrong?”
• “How long does this usually take?”

Step 2: Document the “As-Is” (However Painful)

The first revelation: every request type had a different flow, and some flows were nested inside others like some sort of enterprise Matryoshka doll.

• User account requests go through a dedicated system for approval (security check and budget approval because licences cost money), then Service Desk creates the account, then Training Team delivers mandatory onboarding. Simple enough.

• New portal requests start with Service Desk building an initial portal, then BA sizes the work and gets budget approval from the customer, then BA builds the portal whilst simultaneously kicking off profile work (if needed) because profile builds are so slow you can’t wait for them sequentially.

• Profile builds are an iterative nightmare: BA sends requirements to .NET team → they build in dev using spreadsheets → BA sanity-checks for typos and metadata relationships → if issues, loop back → if good, .NET creates a release bundle → DBA + Release Manager deploy to TEST → Test team does system testing → Release Manager deploys to STAGING → BA does UAT with users → if it fails, back to the beginning → if it passes, Release Manager deploys to PRODUCTION → Service Desk closes ticket.

Oh, and there’s no formal retirement process. Portals just… linger… forever…, I suppose.

Step 3: Build the “To-Be” (With Buy-In)

Armed with the ugly truth, I could finally propose improvements:

Key principles for the future state:

1. All requests must create a Service Desk ticket with defined SLAs (no more “we’ll do it when we do it”)
2. Complexity-based routing: Simple changes stay with Service Desk for speed; complex work gets BA involvement and proper time codes
3. Profile work comes to me instead of .NET team - they’re busy, they don’t want it, I’m literally hired to do it
4. DBA team remains the production deployment gatekeeper (safety net, quality gate, all good)
5. Training Team gets involved when needed to ensure customer success

The critical political bit: if work requires a BA to size it and assign a time code, it’s project work with proper funding. If it’s simple enough for Service Desk or DBA to handle via BAU tickets, it’s service delivery with SLAs. This distinction protects everyone - I don’t end up doing unbilled work for weeks, Service Desk doesn’t get overwhelmed with complex changes they can’t scope, and BAs don’t become a bottleneck for trivial requests.

Step 4: Iterate, Iterate, Iterate

I showed the first draft to the BA team. They pointed out I’d completely missed the customer approval step for estimates (oops). I showed it to Service Desk. They clarified that a dedicated account management process handles account approvals, not them. I showed it to Training Team. They gently reminded me that new users need mandatory training, not just optional training.

Each iteration made the diagram more complex but also more real. Yes, it’s a monster now. Yes, there are seven different request types with different flows. But it’s accurate, and accuracy is worth more than simplicity when you’re trying to de-risk a fragmented mess.

The Tools: Mermaid, Draw.io, and the Quest for Visio

I built these diagrams using Mermaid - a text-based diagramming syntax that’s honestly brilliant. You write something like:

graph TD
    Start[Request] --> ServiceDesk[Service Desk: Create Ticket]
    ServiceDesk --> BA[Business Analyst: Size Work]

And it generates a proper flowchart. For someone who spends their day in code editors, this was perfect. Diagrams as code! Version control! No dragging boxes around in a GUI!

However, the political reality of enterprise IT reared its head: we can’t use Mermaid diagrams in production because we need to sanitise company-specific names before sharing with external parties, and Mermaid doesn’t give you that level of control once rendered.

Fair enough.

So the workflow became:

1. Build diagram in Mermaid (fast iteration, easy to update)
2. Import into Draw.io (which natively supports Mermaid!)
3. Edit/sanitise any sensitive information
4. Export as Visio format (.vsdx) for the Visio users
5. Keep the .drawio version for my own sanity

Draw.io’s Mermaid import is straightforward: Arrange → Insert → Advanced → Mermaid, paste your code, done. You get editable shapes you can rearrange and modify, which is exactly what you need.

[Note: If you’re reading this on my blog and the diagrams below look odd, that’s because Astro doesn’t natively render Mermaid. I’ve simplified them to standard Markdown for readability, but the full interactive versions live in Draw.io now.]

The Result: Clarity, Accountability, and (Maybe) Fewer Finger-Pointing Sessions

What did we achieve?

For the Business Analysts:

• Clear understanding of when they’re needed (complex work requiring estimates and time codes)
• Protection from being a bottleneck for simple changes
• Defined handoff points so they know when work leaves their desk

For Service Desk:

• Defined scope: user accounts, simple changes, initial portal setup, security groups
• SLA-driven work (eventually, once we agree the SLAs)
• Clear escalation path for complex requests

For me (Platform Admin):

• Ownership of profile builds with proper time code allocation
• No more unbilled work on undefined projects
• Clear accountability: I close tickets when work is done
• De-risked position: everyone knows what I’m responsible for

For Training Team:

• Recognised as essential for user onboarding and customer success
• Clear triggers for when training is needed (new users, new portals, significant changes)
• Autonomy to close their own tickets

For the organisation:

• Documented process means we can onboard new team members
• Complexity routing means work flows efficiently
• Defined SLAs mean customers know what to expect (once we bloody well agree them)

The Lessons: Process Mapping as a Risk Mitigation Strategy

If you’re in a similar situation - inheriting an undocumented mess, fragmented ownership, unclear accountability - here’s what I learned:

1. Interview stakeholders separately first

People are more honest in one-on-one conversations. The .NET team told me they didn’t want profile work and it always went to the newest team member. They wouldn’t have said that in a group meeting.

2. Document the “As-Is” honestly, even if it’s embarrassing

Don’t document the process you wish existed. Document the actual reality, including the workarounds, the bottlenecks, and the bits where someone just emails their mate instead of following procedure.

3. Use visual tools, not prose

A flowchart shows handoffs, decision points, and loops in a way that a written procedure simply cannot. When I showed people “you are here in this colour, and this is where work goes next,” they immediately understood their role.

4. Iterate with stakeholders

My first draft was maybe 40% accurate. The second was 70%. By the fourth iteration, we’d captured everything, including edge cases like “what if UAT fails in staging” and “who closes the ticket when Training is involved.”

5. Define complexity boundaries

The distinction between “Service Desk can handle this via SLA” and “This needs BA involvement and a time code” is political gold. It protects everyone’s time and makes accountability crystal clear.

6. Accept that some processes are messy

The profile build cycle has seven steps including iterative loops and three different environments (TEST, STAGING, PRODUCTION). That’s not because we’re incompetent; it’s because software deployment in regulated environments is inherently complex. Document it honestly.

7. Use the right tool for the right audience

Mermaid for rapid iteration and version control. Draw.io for collaborative editing and sanitising sensitive info. Visio export for the people who insist on Visio. Whatever gets the job done.

What’s Next: The Retirement Process (And Other Adventures)

We still don’t have a formal retirement process. Apparently portals just live forever once created, slowly accumulating technical debt like digital barnacles.

That’s the next bit to tackle: what happens when a customer no longer needs a portal? Data migration? User communication? Service Desk deactivation? Platform Admin removal? DBA cleanup? Training documentation updates?

It’s going to be another monster diagram, I’m sure.

But here’s the thing: I no longer feel like I’m drowning in an undocumented mess. I have a map. It’s a complicated map of a complicated system, but it’s a map. And when the next crisis hits (and it will), I can point to the flowchart and say, “Here’s where the process broke down, here’s who owns this step, here’s how we fix it.”

That’s worth every hour spent in stakeholder interviews and iterating on diagrams.

Closing Thoughts

I came into this role expecting to write code. Instead, I’ve spent a year gently poking a fragile system,s cribbling down my thoughts at the time and ultimately writing process documentation, and honestly? It’s been just as valuable.

If you’re a developer who finds themselves suddenly responsible for a legacy system, or a project manager trying to untangle organisational spaghetti, or just someone who inherited a mess and doesn’t know where to start: map the process first.

You can’t optimise what you don’t understand. You can’t assign accountability without defining scope. You can’t de-risk your position without documenting exactly what you’re responsible for.

And sometimes, the best code you can write is a flowchart.

Have you tackled process documentation in a chaotic environment? Found Mermaid useful (or frustrating)? Wrestling with legacy systems that have no documentation? I’d love to hear about it. Drop me a message or leave a comment below.

P.S. - If anyone from Oracle is reading this and wants to sponsor a blog post about how WebCenter Portal is actually quite good once you understand it, I’m open to bribes in the form of official documentation or perhaps just a sympathetic ear.