Thank you very much.
Thank you, yes.
And apologies, as we say, for being the third British...
Is this on? Can you hear me?
We've got feedback just being louder to the back of the room.
Okay, how's this?
Okay, alright, I'll try and stay standing up.
And apologies for being the third British speaker, as we said.
Maybe I should start off with...
But I am another British speaker, writing in American English.
I won't say too much about that, so I may get into trouble at work.
But also, carrying on the same theme, we use the same docs as code.
I'm a writer at Couchbase. We're a large NoSQL database company.
Other NoSQL databases are available, so I won't be talking too much about Couchbase purely.
Going along with a lot of what's been said, we do that docs of code.
We do the local linting and everything else and rendering.
Although we're actually bumping up against a lot of limitations around the ideas of docs as code.
We have problems where having a mixed code and docs repository is not necessarily the best answer.
And we do have several dozen separate docs repositories for different products.
We run up against all sorts of problems.
But I'm just here to talk about one particular problem, which I've discovered,
as I've been trying to rewrite a section of our documents.
And that's this over-optimization problem that we sometimes have to make it easier
to maintain docs across versions versus how do we make documentation
less opaque in the source for new contributors.
So I'm not sure how much of a widespread this problem is, how many people are working with scale,
or even in the room how many people are writers versus doc ops versus engineers.
But just to give an example, I mean, for me, how many of you are writers with an interest in doc ops
rather than the other way around? Who's a writer primarily?
So not so many writers. How many are doc ops who care a bit about writing?
So more of an, and how many are just engineers who care about writing?
So much more of you there. So this is interesting because in the first talk in this room,
Lorna described herself as an engineer who has a writing problem.
And a lot of what I'm going to talk about comes from this particular,
sorry, I just had an about me thing. I found the older about.me website.
It was just interesting because nobody uses these anymore and I lost the login 10 years ago.
But there's not much to say about me other than I like plants, especially food plants.
And if we do finish too early, Christoph and I can both answer questions
on systems thinking applied to growing fruit and vegetables, but moving strictly on.
So we're trying to read all that. There's far too many lines for a slide,
but engineers do like to over-optimize. You know you do.
If there's any sort of problem, you know, it's DIY.
Do not repeat yourself and you want to get those optimizations in straight away.
And so as I've been going through old bits of the document, sorry, that's not really very big.
Let's I think I've got it bigger on the next one.
Yeah, I found bits where one of the Java engineers had started once we had a Scala SD-Cache.
Scala SD-Cache as well as a Java SD-Cache started to put things in to keep everything the same file in both,
but just slightly changed to pull out information to tell you where they are.
But there were only two different languages to do between out of 10 SD-Caches that we have.
And the more of this sort of stuff you have, the more anybody wanting to do a quick edit on your docs
who doesn't know all of the structure of your docs has to start digging and finding things.
But this isn't too bad. And I should say as well before we go into deeper waters
and there are some very deep waters in our docs of trails of abstraction which lead down a long, long way.
But I understand why all the people who were involved did it and there were extremely good reasons at the time
because we have too few people doing too much work like most places
because everything moves so quickly in software and we always have more products with the same resources to deal with them.
But I just want to take a quick example which started when I wanted to do a quick edit on our mobile product.
We have an offline first mobile database which syncs with the main database
and it's embedded with various languages depending on your mobile device
or even Java desktop as well as Java on Android.
And I couldn't see the bit of a page I needed to edit here because I couldn't work out what was going on.
I could see I needed to start looking at various things which were being included like these include partials up there at line 8.
And then there's the page context for Java adoc.
So I looked for that.
We're using Antora with ASCII doc and Antora has a structure where for each module you will have the pages,
you will have partials which are being pulled in whether they're partials with attributes or partials with chunks of text that you're reusing.
But these weren't in the partials module.
If you look closely after the partial dollar string there's an underscore.
There was already a separate underscore partials directory within pages as well as the partials directory which you'd expect to find.
So following that down I found this.
This was already including more partials so root pages, page context and so on.
But there were some other strange things going on here.
I'm not sure if you can see it, but I'm not sure if you can see it.
I'm not sure if you can see it, but I'm not sure if you can see it.
I'm not sure if you can see it, but I'm not sure if you can see it.
I'm not sure if you can see it, but I'm not sure if you can see it.
It made sense to them to put all this stuff in so that each time new versions came out,
each time this stuff was reused in other language versions.
It wouldn't break for them and they wouldn't have to do any extra work.
But for someone trying to fix a quick bug already they're going down more layers, three layers.
We get to that general page parameter after the Java one.
And this one just followed on to another one which followed on to 223 lines of parameters.
Now, at this point I had just given up on all hope of doing a quick fix in these docs
and I don't expect anyone else will ever do a quick fix on them.
And I know the people who are now maintaining the docs are changing this section to flatten this out.
I don't like stop signs, they're a bit sort of warning-y.
Let's have a clear calm sky to relax.
So clearly you can over-optimize too far, but if you don't take shared cases
and pull them together with shared files of text with useful parameters,
you get to a point where you are repeating yourself way, way too much in docs.
Especially so for example, our server SDKs we have ten different languages and counting.
And there's a lot of common content if it's on something like field level encryption.
Most of it's the same as just a very tiny code snippet needed to show the API.
It's mostly talking about what you need to know, what the limitations are, how to implement it.
So maybe we could start with just some simple things here.
So a partial sphiyog with attributes to each module.
Now, the thing is we're doing it this way in Antora and ASCII Doc.
You have to include the partial sphiyog in each document file.
So instead, there's a much better way of doing it.
And that's just to stick it in the Antora YAML file at the base of each repo
and just put all the attributes together.
It's hidden from the new user to ASCII Doc because they don't know that this stuff is there
so there's things you can do to point the way.
But let's just pause and think about these dozen, well, eleven, their attributes.
It's everything which would need to be changed from a change of a patch release
or when this stuff is replicated to a new .minor.
Or when we pull in a common file and we're talking about that SDK and doing it.
And no more.
So I think for what I'm doing at the moment, the balance is about right.
But the reason I'm here talking now and it's interesting,
Jack mentioned his talk with his first FOSDEM talk.
This is my first FOSDEM talk but I last gave a talk on edible landscaping.
I mentioned the gardening stuff before but the reason I'm here is not so much a talk
as a set of open questions because we're all here with an interest in making maintainable docs.
And so when we get to the end in a couple of slides, what I really want to know is
how have you been able to find a balance?
Is this something that you've come up against where you've got new contributors coming in
to help with your documentation and you have to spend way too much time
helping them understand what you're doing or do you not have enough contributors to make it worthwhile
and given shortage of writing resources, it's always going to be better to slightly emphasize the optimizations.
So that balance is really what I'm here for to find out because I don't know.
What I've showed you before on that Scala one is about where I'm at
but I'd like to know what other people think so please, over to you.
Alright, this is always a dangerous format when you open it up.
Yes.
Who has this problem also?
Who's running a project for this?
Abstractions keeping in.
As I say, we're right on the edge of Docs' code sort of breaking down under the strain of how much stuff we have going on.
So maybe we are the only ones and other people will have this problem later.
It reminds me of the problem of abstraction in code as well.
I think the shape of the problem is very similar.
So I think my answer, even though I don't write a lot of Docs, my answer would be the same.
It depends.
People that work with the system a lot and they are interested in all of the abstractions and it's necessary.
Then you go more towards that side.
If you have a lot of beginners or people that are less experienced with those kinds of abstractions, then you lean more towards that side.
I don't necessarily see a big difference between abstractions and code versus in like, DocOps.
Absolutely.
So for anyone who didn't hear, there's very little difference between abstractions in code and in Docs.
I'm glad to find people saying there are no clear answers because that means we still get paid for making decisions that LLMs couldn't do.
Can I ask you a question?
Is the couch-based Docs open?
Yes.
So almost all of our Docs are in open Docs reposing GitHub.
Some of them are in Docs' code repose mixed with the code.
And the one for our cloud as a service product, which necessarily has a closed repo for the control plane, we're in the process of pulling the Docs out of that.
And how many external contributors?
Contributions are there, generally speaking.
I know that it's not that common for open source documentation to stop, but how many contributions do you get?
Yeah.
So we're an enterprise company.
Almost all of our customers are large enterprises rather than small groups of developers.
So that cuts it down even more.
And yet we get some customers coming in, putting in pull requests.
Whenever there's a project where people are encouraged to go off to GitHub and contribute to open source code, we tend to get our fair share of people adding in that as well.
So sometimes we do see people coming in and missing how stuff is structured and doing a less helpful contribution, definitely.
Do you have Docs for your Docs?
Yes, but are they up to date?
No, they are not up to date.
I think when I was having this problem I know a lot of modern tooling, which we will be getting to in the next couple of talks, can make things overly complicated for people who just want to fix a typo.
Yeah.
You prefer some in your tip.
We're on the other end of the spectrum where we're a small developer team with a lot of mechanical process engineers that we want them to write.
And often they write things and they want to first each rate 15 times over before they publish and they never come to publishing.
The most important thing is the lowest barrier to actually write something.
So we tend to steer away as far as possible from this abstraction because we see that it's not difficult, but it's like that one tiny thing that maybe doesn't hesitate to actually do that something.
Could Vale help you with removing abstractions?
I don't know about that. We're already using Vale.
I'm repeatedly told on all the faults I have by Vale and I'm getting hardened to it, but I do have a very thin skin.
There's a connective question.
Is this problem one person or is this a systemic problem?
Because it might be that you have one person who's just really enamoured by abstractions, who just keeps adding abstractions.
Well, I mean, these were engineers slash writers who A, loved these abstractions and B, really needed to do them because we just didn't have the number of people needed to deal with this.
They've moved on and we've got new writers who don't have the same engineering background and we want more people getting involved in those mobile docs.
So we are definitely moving away from that.
But it's at balance. We're always going to need some abstractions to make it maintainable.
So I'm rewriting our SDK docs for, well, for 11 SDKs because we've got another one going GA at the moment because our existing SDK docs are awful.
And I know that because I wrote them six years ago.
And, you know, I've always known them about it, but now I can see a way of making them good.
And that includes also dealing with a lot of tech debt and the level of abstraction is about balancing out how to keep that tech debt lower as we go along as well.
Yeah, so we're using a good base flow and we have our own local environments with reviewers and with other people.
We would like to have some one click solution to just fix this comma separately.
So we're doing some experiments with, yeah, hosted editors so that at least you can, although there might be that flash, although you might not be on the same full test, but you don't need to set up a whole system to do something with this.
Absolutely. Yeah. So, so, I mean, you asked earlier about ad docs being open so you can click on edit this doc and it will open up the GitHub repo.
And if you open up that one I showed at the beginning with with all that track, that's when you would be totally lost.
Yeah. Yeah.
I'm an increasing fan of tools like MDX, which is not down plus react components.
And that's great fun in the browser, but terrible for editing.
Yes.
But it's cool. So you keep doing it.
Any other questions, statements, experiences or we can refresh the room for a little bit longer before the next full.
Oh, yes, I could just add that sometimes the abstractions are required because I work for a mechanical industry.
So what happens there is that I use a very same component on different machines.
So the obstruction that cases required because otherwise, I mean, you can't go too much in detail for that component because it could be leaving very different machines.
So that's why in those cases abstraction is, yeah, you have to carefully write what you're writing because otherwise you risk to not being able to recycle that component that piece of writing that, you know, that fire.
That's where I think I'm going to.
There is an answer.
Yeah, the room isn't there, but it's not open source.
So I'm not talking about it.
Well, the tool.
The top of the source.
The stuff that most people.
Yeah, I see.
But the core of the heart, you could be.
I think you're open source.
All right.
Let's move it to that.
By the way, I have one question for the people who created the problem with the many abstractions or the repeated abstractions.
Do you have a way to help them face it?
And maybe they come up with a solution or did you die?
Oh, well, they left the company long ago.
Yeah, very sensibly.
Yeah, yeah.
But thank you for helping me think out loud about our problem.
And it's interesting to see that it's not yet shared in many places.
But that's good because I do like a challenge.
Sorry, one more.
So we have quite a similar problem at my company.
It's the inter-place.
Because we have, let's say, one size fit or inter-place, that can be used in places where I do lane-eskiders, places where I do aqora, and then in places where I do different visual performance.
We are waiting for a thousand of situations, and we have a lot of people there.
And then it's not any additional problem because changing the top lane is a very difficult journey.
We need to get with ten people and change the lane.
So that's, in my company, that's the case.
It's just changing that.
Too much airport for inter-place.
Yeah, those if-defs, they should definitely be the exception rather than the rule.
They're necessary sometimes, but too many and you're lost.
Okay, cool.
I don't know what experience the innovation is using.
It seems like that, traction should be like supporting the US operation concerns,
bringing the documents where they want to just, like, induce a bounce.
But it looked like it was something like real congratulations that you can ask to display something like what we did with Goji,
and the structure of the installation, and what we construct and take like more depth for you in the end of the story.
But here you need to have the knowledge of all the sub-cores, and if you do as well,
from the power that you showed, it seems like it is your best knowledge of what happened to you,
and what you think that happened to you.
Yeah.
Yeah, so I think one way around that limitation that I am putting into the sort of,
I should have put it on a slide is that the new pages are going to have comments at the beginning pointing out everything that's connected,
where the page is, where it's pulling from, and make it clear up front for editors.
It says a note for editors and does that.
I should have, I've got it open here, but I can't, for some reason, my screen mirroring is not the right sort of mirroring to Dragimax up there to show the thing.
It's the most better time to say that.
See Richard after the talk.
Thank you.