[00:00.000 --> 00:13.560]  Hello, everyone. My name is Andrea. I am a product specialist for documentation at Agen,
[00:13.560 --> 00:21.480]  and I'm happy to be here today to share about how we use graph for our documentation both
[00:21.480 --> 00:27.840]  internally and externally. I used to be a technical writer for more than five years,
[00:27.840 --> 00:34.440]  and before that I used to be a research scientist. But enough about me. Let's look a little bit
[00:34.440 --> 00:42.560]  into Agen, the company that I work for, so we can better understand the needs for documentation
[00:42.560 --> 00:50.520]  internally and externally. Agen is a financial technology platform, which has seen a lot
[00:50.520 --> 00:57.000]  of growth since its inception back in 2007. These days we are over 2,000 employees of
[00:57.000 --> 01:05.920]  more than 100 nationalities across the world in 26 offices. In development, we use write
[01:05.920 --> 01:17.320]  and maintain open-source software. And to keep all of this together, we have internal hubs
[01:17.320 --> 01:23.360]  for knowledge sharing and externally to build that confidence in the businesses that we
[01:23.360 --> 01:30.440]  work with and to help them integrate. We also have documentation for them. The team,
[01:30.440 --> 01:37.720]  doing documentation at Agen, the Docs at Agen team, now has around 30 people. This picture is a bit
[01:37.720 --> 01:45.680]  outdated, so a bit less than 30 people in there. It was taken back in November when we had an
[01:45.680 --> 01:54.080]  off-site to work on objectives for 2023. But getting back to the point, so about half of the
[01:54.080 --> 02:02.760]  Docs team is technical writers who work closely with the development teams to produce integration
[02:02.760 --> 02:15.640]  information that our clients use. And the other half is more product-focused. They look after
[02:16.480 --> 02:27.960]  our graph implementation and try and make it as user-focused as possible, where the users are
[02:27.960 --> 02:34.040]  both the people reading the documentation as well as the people writing the documentation. So we've
[02:34.040 --> 02:40.800]  got front-enders, back-enders, we've got automation engineers, we call them DocOps engineers. We've
[02:40.840 --> 02:50.880]  got product managers and designers working for us. And it would be a bit incomplete if we were to not
[02:50.880 --> 02:58.080]  mention all the contributors. So the external documentation are not open source, but they are
[02:58.080 --> 03:05.960]  inner-sourced, which means that our colleagues at Agen can contribute suggestions if they find
[03:05.960 --> 03:11.600]  something that they think is not quite right, or they have an idea of how to improve things. And the
[03:11.600 --> 03:18.800]  internal knowledge base is open for everyone to edit. And in the last four years, there have been
[03:18.800 --> 03:27.560]  over 3,000 people who have contributed to the internal knowledge base. Now, some of you might have
[03:27.560 --> 03:33.640]  been wondering what exactly is graph. It's an open-source flat file content management system. It's
[03:33.680 --> 03:47.120]  got a really big community around it, and it has consistently won some awards as a product. And for
[03:48.400 --> 03:56.880]  support with your graph implementation, there is also Trilby Media, a company of the people who
[03:56.920 --> 04:06.200]  have written graph. Graph itself is written in PHP. The content is in Markdown. You can also do
[04:06.200 --> 04:13.520]  templating using Twig. And its features are greatly extensible through its powerful API and
[04:13.520 --> 04:26.360]  package management. So some of you might have seen this talk from back in 2018 from Alexei.
[04:26.880 --> 04:37.120]  who was then talking about the migration to graph from Confluence. He was emphasizing how we chose
[04:37.120 --> 04:42.280]  graph because of the possibilities it offers in terms of collaboration, contribution, and
[04:42.280 --> 04:52.160]  extensibility. Other benefits were obviously it being open-source, which meant no fee per user,
[04:52.160 --> 05:00.520]  which used to be the model at the time with Confluence. It also allowed us to unify how we do
[05:00.520 --> 05:06.520]  documentation internally. So before migrating to graph, there were several CMSs serving various
[05:06.520 --> 05:13.080]  needs. The knowledge was quite fragmented. And switching to graph enabled us to create a go-to
[05:13.080 --> 05:20.200]  place for internal knowledge sharing. Also moving away from Confluence allowed us to have full
[05:20.240 --> 05:24.040]  control over the look and feel of the website, believe it or not. And I could hardly believe it
[05:24.040 --> 05:29.520]  when people were telling me that in order to customize the look and feel of the Confluence
[05:29.520 --> 05:34.240]  website, they had to modify the DOM using JavaScript. There was a very roundabout way of
[05:34.240 --> 05:47.560]  doing it. And also being able to fully customize both the end user experience and the writer
[05:47.560 --> 05:57.320]  experience, according to their needs, is a big plus that graph was bringing. Now, in terms of
[05:57.320 --> 06:02.480]  this talk, we're going to look at the graph implementation from a tech perspective, looking
[06:02.480 --> 06:11.280]  at how the code base is organized and what kind of quality assurance and customizability we do
[06:11.840 --> 06:17.520]  with it. We're also going to look at the implementation from a people perspective, all the
[06:17.520 --> 06:22.640]  different ways that people collaborate and create content using graph. We're going to talk about
[06:23.440 --> 06:28.800]  the collaboration with the open source project maintainers themselves. And then we're going to end
[06:29.840 --> 06:36.640]  looking into the crystal ball into what we expect or what we're looking forward to in terms of the
[06:36.640 --> 06:49.120]  future. Now, for the tech part, the really neat thing about graph is that it's possible to have a
[06:49.120 --> 07:00.560]  single code base that then enables several websites to be deployed. This is because we have the
[07:00.960 --> 07:06.960]  graph code base in a separate repo from the various content repositories. And then for each content
[07:06.960 --> 07:14.400]  repository, you can even have them deployed to several domains, according to their own specific
[07:14.400 --> 07:19.280]  domain base configuration file, which can even turn on and off various features depending on domain.
[07:20.960 --> 07:29.280]  For example, this happens, we use this for the external documentation, where we have two domains,
[07:29.280 --> 07:35.360]  we have an internal domain for staging environment and a public domain for the
[07:35.360 --> 07:44.880]  documentation that our clients use. Graph also supports both static and dynamic versions of a
[07:44.880 --> 07:51.120]  website. For public documentation, we always use static HTML websites for security reasons,
[07:52.080 --> 08:02.320]  but internally, so that users can immediately see the changes that they've saved,
[08:02.320 --> 08:08.720]  we do use the dynamic version of the website. So talking directly to the server.
[08:10.160 --> 08:17.360]  Graph also allows quite finely grained control of access to people, so you can restrict
[08:18.000 --> 08:24.240]  read write access based on user profile, or you can even do this outside of graph by putting a
[08:24.240 --> 08:34.160]  particular server instance behind a firewall. So to look at this visually, we have the one
[08:34.160 --> 08:40.240]  graph code base that then together with a content repository and domain config files
[08:41.040 --> 08:49.280]  will produce one website. And then from the same code base together with a different content repo
[08:49.280 --> 08:54.960]  and say a domain config file for dynamic websites will produce the dynamic website.
[08:56.960 --> 09:03.280]  And then to get a static website, for example, all you need to get a static website for
[09:04.240 --> 09:10.160]  the same content repo, all you need is a domain config file for the static version.
[09:10.800 --> 09:19.920]  And then you already take the single graph code base together with the content and produce the
[09:19.920 --> 09:31.840]  static website. In terms of quality assurance, our DocOps engineers are working hard to write tests.
[09:33.280 --> 09:38.000]  For example, we never publish broken links. That's because we have the broken link checker,
[09:38.000 --> 09:43.840]  which produces a report like what you see here, telling writers where the broken link is,
[09:44.400 --> 09:50.160]  so that it can go fix it. We also have security checks, so we have to be very careful
[09:51.520 --> 09:57.920]  for compliance reasons, what kind of card numbers we use, for example, in code samples.
[09:58.640 --> 10:07.200]  So this kind of check will always prevent people from publishing if the test fail.
[10:07.200 --> 10:16.880]  But there are, say, you know, less crucial things like maybe like small style checks or
[10:16.880 --> 10:24.240]  like small typos that we will not stop publishing for. People, writers still get the reports for
[10:24.960 --> 10:28.800]  this, and they will fix it, but it won't stop publishing.
[10:31.920 --> 10:39.280]  And one of the great strengths of Graph customization, this can be done at various levels.
[10:39.280 --> 10:45.040]  So first of all, the look and feel can be customized using various themes. As you can see here,
[10:45.040 --> 10:53.520]  two fairly different looking websites. We can establish various page templates where we see
[10:53.520 --> 11:04.800]  that there is recurring content of a certain shape. We also build custom components for the UI.
[11:05.520 --> 11:13.760]  So if we identify, for example, a component we built last year was for decision trees.
[11:13.760 --> 11:24.160]  So for example, for people doing tech support internally or for people trying to choose their
[11:24.160 --> 11:30.400]  particular online payments integration with Adien, they would need to either read a few
[11:30.400 --> 11:36.160]  pages or they could take this, like answer a few questions, and they'll get a recommended
[11:36.160 --> 11:44.240]  integration. So that kind of decision tree component is something that we built for Graph.
[11:45.120 --> 11:48.320]  And because we have a single code base that can work with several repos,
[11:49.920 --> 11:55.440]  that component can be enabled on various websites, so whichever ones need it.
[11:57.040 --> 12:03.920]  And then also another neat thing is the extensibility using plugins, which means that we can add
[12:04.880 --> 12:14.320]  new functionality in a modular way. We particularly use this for the internal knowledge base for Hub
[12:16.720 --> 12:23.280]  to create integrations with other tools we use internally. So for example, to allow colleagues
[12:23.280 --> 12:30.800]  to easily embed content from, say, the issue tracker or from the internal stack overflow,
[12:30.800 --> 12:36.800]  because like I said, we want Hub to be the go-to place for knowledge sharing internally,
[12:36.800 --> 12:43.200]  and therefore it needs to provide good connections to all the other tools that are used within the
[12:43.200 --> 12:48.480]  company. Now, all of this, of course, does not come without these challenges.
[12:51.040 --> 13:00.320]  The team has grown probably about five times because there was one developer when Alexey
[13:00.320 --> 13:11.280]  gave his talk in 2018. And we now have five developers working on the various projects.
[13:13.120 --> 13:20.560]  Part of getting here was defining and enforcing workflows so that everyone works consistently
[13:21.520 --> 13:28.720]  and predictably, which also helps, makes for easier troubleshooting.
[13:30.640 --> 13:35.840]  Another challenge that came with us having offices across the world meant that
[13:38.240 --> 13:46.000]  if the internal documentation was hosted in the Netherlands, our colleagues over in
[13:46.560 --> 13:50.960]  Australia or Singapore were having to wait quite a long time
[13:53.680 --> 14:03.760]  to see the content that they needed. And this came back as a pain point from the users. So
[14:06.080 --> 14:13.440]  we started deploying the internal documentation to service in APAC as well.
[14:13.440 --> 14:21.040]  So then we also had to deal with thinking changes across services worldwide. So we've done that one
[14:21.040 --> 14:34.400]  too. Right. Moving on to people and how they work together. And Graf does enable various ways of
[14:34.400 --> 14:42.560]  collaborating and managing content. And for this part, I'm going to look at the internal docs
[14:42.560 --> 14:47.280]  and the external docs in parallel so we can better see
[14:50.880 --> 14:58.240]  the various characteristics depending on how people collaborate and how they create content.
[14:59.120 --> 15:06.640]  So for the internal documentation, it's run wiki style, which means that anyone can make changes.
[15:07.600 --> 15:13.440]  People mostly make changes using the browser editor. We also accept poor requests, but
[15:14.400 --> 15:18.160]  relatively small percentage of people will raise a poor request.
[15:21.360 --> 15:25.600]  The internal documentation also has page and section owners visible at the top of the page so
[15:25.600 --> 15:31.680]  that people can easily find out who to contact if they have questions or if they spotted something
[15:31.680 --> 15:38.400]  wrong on the page. And our colleagues from development have also set up
[15:38.400 --> 15:41.600]  certain integrations with code repositories and internal tools
[15:44.240 --> 15:51.680]  to again facilitate this communication and knowledge sharing in one place.
[15:52.800 --> 15:58.960]  Now in terms of the external documentation, like I said, there is the group of technical
[15:58.960 --> 16:06.320]  writers who write and maintain the content. Now unlike Hub, unlike the people writing content
[16:06.320 --> 16:14.000]  for Hub, people writing docs mostly use their ID. They commit their markdown changes and
[16:15.760 --> 16:21.120]  push them to the remote. They will check the state of the docs locally and all of that. So
[16:21.120 --> 16:25.920]  in other words, they use a doc's code approach to creating and maintaining content.
[16:28.960 --> 16:35.760]  I kind of mentioned this before that we have a way for people to suggest changes internally.
[16:36.320 --> 16:46.880]  So we have a technical writer on duty every week who reviews changes coming from colleagues.
[16:49.920 --> 16:54.800]  Because there is this small group focusing on curating this content and they are quite,
[16:55.440 --> 17:01.440]  so like text-heavy-day tree documentation is code, there is a lot of reuse and parameterization
[17:02.560 --> 17:09.120]  in the external documentation trying to find that sweet spot, that balance between
[17:13.760 --> 17:19.360]  writing content in a scalable way, so reducing the maintenance burden but also without
[17:20.400 --> 17:23.600]  increasing the cognitive load for maintenance too much.
[17:25.360 --> 17:35.280]  But also an interesting thing that has, well, interesting thing that has happened since 2018
[17:35.280 --> 17:42.560]  is that Agen as a company went from being a payments company to a financial technology
[17:42.560 --> 17:49.120]  platform. So this means that on the one hand, the payments products stayed, became,
[17:50.080 --> 17:54.800]  so like the bread and butter of what the company does and the basis for a lot of other products.
[17:55.760 --> 18:05.920]  And those products had more and more releases, so there have been iterations, several versions
[18:05.920 --> 18:13.120]  to document. But on the other hand, extending into financial products meant that a series of other
[18:13.120 --> 18:17.680]  new products were built which also needed documentation. So there has been a lot of
[18:17.760 --> 18:26.960]  content growth along both of these axes. So let's have a look at how the company growth has,
[18:26.960 --> 18:33.040]  is reflected in documentation as well. So in terms of internal documentation,
[18:34.880 --> 18:42.560]  we all use it, right? So the fact that the company has grown about three times since 2018
[18:42.560 --> 18:48.800]  means that the audience has also grown just as much. The content itself has
[18:50.400 --> 18:55.360]  grown two and a half times. Last I checked with the product specialist for Hub,
[18:56.080 --> 19:03.920]  we had more than 12,000 pages. That is a lot of content. And those 12,000 pages have been
[19:03.920 --> 19:14.400]  written by over 3,000 people in the last four years. Yeah, I was quite surprised when I first
[19:14.400 --> 19:21.040]  saw these numbers. Now for the external documentation, the audience has also increased
[19:21.040 --> 19:27.520]  even more than the internal one. So this is another aspect of how company growth
[19:28.400 --> 19:36.000]  can be seen in docs analytics. The amount of content we have in the docs has also increased
[19:36.000 --> 19:44.000]  undoubtedly with all the new versions, all the new products. But somehow in a more controlled,
[19:44.000 --> 19:50.800]  curated way. And maybe when we look at the challenges in the next slides, it might become
[19:50.800 --> 19:57.280]  more apparent why the growth for external documentation has been a bit more controlled.
[19:58.720 --> 20:07.840]  And of course, definitely worth mentioning that more than 350 colleagues have suggested changes
[20:08.640 --> 20:14.080]  in the last three and a bit years because the suggest changes flow is a bit more recent.
[20:14.640 --> 20:21.200]  So we get on average 100 people a year making suggestions and that is very, very valuable to
[20:21.200 --> 20:30.880]  us because with thousands of pages of documentation, the help that we get from people suggesting
[20:30.880 --> 20:40.640]  changes is invaluable. And now let's look at the challenges that come with the growth in number
[20:40.640 --> 20:46.960]  of people and growth in content. So again, looking at hub, the internal documentation,
[20:48.720 --> 20:54.880]  or the last four years I've taught us is that we need to have a good strategy for content ownership
[20:54.880 --> 21:01.840]  long term because time passes and people come, people go, but the content remains. And there
[21:01.840 --> 21:08.160]  needs to be a plan in place for what happens to that who becomes responsible for it. There's also
[21:08.160 --> 21:13.840]  the issue of broken links. So I was saying earlier that in the external documentation,
[21:13.840 --> 21:19.360]  we never publish a broken link. And that is true. But with internal documentation, we don't have
[21:20.080 --> 21:26.160]  that kind of flow in place because the editing flow is also different. And we are looking into
[21:26.160 --> 21:33.760]  possible ways that we can let people know when links that they have in sections that they own
[21:33.760 --> 21:39.840]  are broken. This normally happens when other parts of the internal documentation that they
[21:39.840 --> 21:46.400]  refer to have been restructured, pages have been removed or reorganized. So yeah, that's
[21:46.400 --> 21:53.920]  definitely something we're looking into. Also, empowering people to write good content is important
[21:55.600 --> 22:00.880]  and making them feel responsible for the content that they've written because writing the content
[22:00.880 --> 22:09.040]  is not enough. It's great that they have written it. But this mindset that once you've written
[22:09.040 --> 22:17.440]  something, you're responsible for it is something that we need to work on a bit more.
[22:19.520 --> 22:25.120]  Now, in terms of the external documentation, one of the pain points that we see from feedback is that
[22:25.760 --> 22:32.880]  it's easy to pull out of sync with other platforms that we have. So for example,
[22:32.880 --> 22:37.760]  documentation versus the marketing website or versus the internal documentation. And this is
[22:37.760 --> 22:40.720]  because the same information is maintained manually by different people.
[22:43.440 --> 22:54.160]  Needing to scale complex content means that we need to have some way of having the same
[22:54.160 --> 22:59.520]  information being shown everywhere, offering a consistent experience in terms of navigation and
[22:59.520 --> 23:07.200]  things like that. We already have ideas for how to tackle this. I'm going to defer this to the last
[23:07.200 --> 23:14.640]  section about the future. Something else that we get is I was saying with the passing of time,
[23:14.640 --> 23:19.200]  several software versions, we find that users do ask for older versions. So versioning is something
[23:19.280 --> 23:25.520]  that we're also working on. Versioning for documentation. And that can be a whole separate
[23:25.520 --> 23:33.360]  talk in itself. So maybe see you next year. And as you might have seen, I've been avoiding the last
[23:33.360 --> 23:40.400]  point for both because finding relevant content quickly is a continuing challenge, especially
[23:40.480 --> 23:49.360]  in a climate of growth. And that is where search and information architecture have to be
[23:50.480 --> 23:57.280]  on point. And continuously iterating on that and seeing what works, what doesn't work for people
[23:58.480 --> 24:01.520]  is a core part. But then also looking at how to
[24:02.800 --> 24:06.960]  show people only the information that is relevant to them is something we're also exploring.
[24:07.600 --> 24:14.560]  Now, in terms of collaboration with the open source community, we have a direct relationship
[24:14.560 --> 24:22.080]  with the graph project maintainers. We've sponsored building certain plugins, which we
[24:25.280 --> 24:33.440]  have then open sourced. So some plugins are for our own internal use because they are very
[24:33.440 --> 24:39.520]  business case specific. But we've also collaborated on plugins that we've then open sourced.
[24:41.600 --> 24:45.920]  And we also contribute bug fixes to the code repository.
[24:49.280 --> 24:56.480]  Moving on to look at the future, I'm only going to look at the biggest challenge that I am very
[24:56.480 --> 25:01.440]  excited about tackling, which is scaling consistently across all the platforms that we have.
[25:02.400 --> 25:06.000]  And now that I'm looking at this diagram, it kind of looks a bit like a present, doesn't it?
[25:07.200 --> 25:14.720]  With a hat. So this inconsistency that I was saying, we're starting to see
[25:15.520 --> 25:19.040]  between the different platforms, not all of which are running on graph.
[25:20.960 --> 25:27.680]  We want to create a single source of truth. And the interface for inputting the information
[25:27.680 --> 25:35.840]  for the single source of truth is probably also going to be an instance of graph using
[25:35.840 --> 25:41.680]  the same one code base that I was mentioning at the beginning. So this is for the kind of
[25:41.680 --> 25:46.160]  information that cannot be generated automatically from code. So this is not for things like API
[25:46.160 --> 25:53.680]  reference. This is for things like emerging properties of various features. So something
[25:53.680 --> 26:01.040]  that is not just a flag in the code. This is something that the product teams will be responsible
[26:01.040 --> 26:10.080]  for. And having using graph for this means that they'll be able to have the same familiar user
[26:10.080 --> 26:17.120]  experience when inputting information about their product as well. So then in the future,
[26:18.080 --> 26:22.080]  other systems, whether they're running graph or not, will be able to use the same information
[26:23.040 --> 26:33.280]  that will be accurately rendered in all these different portals. So maybe see you in another four
[26:33.280 --> 26:47.600]  years to tell you how this one went. So let's move on to the Q&A session. Thank you for your
[26:47.600 --> 26:49.600]  attention and see you in a bit.
[27:06.160 --> 27:15.360]  Okay, so thank you. I think that we have so we just have a couple of minutes for questions.
[27:16.320 --> 27:22.480]  And then in three minutes, we'll get into the next talk. So if you have any questions,
[27:26.160 --> 27:27.600]  don't hesitate to put it in the chat.
[27:30.640 --> 27:33.120]  In three minutes, we'll get into the next talk.
[27:34.000 --> 27:47.600]  Yeah, I did put a question. Me, Andrea, the speaker, have put a question in my own talk.
[27:47.600 --> 27:52.240]  Because I was wondering, I was curious how many people would already be familiar and
[27:52.240 --> 27:56.240]  with graph because me, like myself, I only found out about it when I started my current job.
[27:56.960 --> 28:02.800]  So, yeah, I was just curious within the community if there are people who use it,
[28:02.800 --> 28:06.800]  but it seems that it's, well, at least amongst the people here is not that
[28:09.040 --> 28:09.520]  well-known.
[28:18.160 --> 28:24.320]  Indeed, on Mayan, at least I didn't know about it. Since we started talking about it at first
[28:25.280 --> 28:29.920]  I think it was one or two years ago, but it's nice to see that it's also evolving.
[28:42.960 --> 28:44.400]  Yeah, there has been one.
[28:49.520 --> 28:51.120]  Yeah, sorry, there is a bit of a quarrel, I think.
[28:52.080 --> 28:56.080]  Yeah, I'm not sure which stream to mute.
[28:57.520 --> 29:00.640]  Should one of us maybe read the question that was asked in the chat?
[29:07.840 --> 29:12.480]  So, the question from Mungal, is there any integration with ECM CSP products to include
[29:12.480 --> 29:16.400]  documents and preview on the website? I can see that NextCloud is provided,
[29:16.560 --> 29:20.800]  but only for backup purposes.
[29:24.160 --> 29:33.920]  Yeah, so, like I said, we do use NextCloud, but we don't embed it in the
[29:34.640 --> 29:38.480]  internal knowledge base per se. So, for any need to access that, we link out.
[29:39.360 --> 29:42.960]  I'm pretty sure part of the reason for that is because some NextCloud files have
[29:42.960 --> 29:49.200]  restricted access and having this double layer of access restriction
[29:50.560 --> 29:56.240]  was seemed a bit unnecessary, but I don't think we've had requests for it either.
[30:00.160 --> 30:06.400]  Cool, so, I think that no, if anyone wants to ask some questions, we have the room
[30:07.280 --> 30:14.160]  that we are discussing in, which is now open. So, I guess that you can take questions here.
[30:14.160 --> 30:19.200]  On my end, I will switch to the next talk for the dev room. So, thanks a lot, Andrea,
[30:19.200 --> 30:23.440]  for coming and thanks for your presentation. It should be online on the website very soon,
[30:24.160 --> 30:29.600]  if I'm not mistaken. Yeah, thanks for having me. I'll see you around. Thank you. Bye.
[31:06.400 --> 31:07.200]  Bye.
[31:36.400 --> 31:37.780]  you