We identified the following weakness in the old system:

• Guru has a centralized search feature, but the information on Guru is far from complete, and a great many articles are outdated.

• The Word documents, though often more thorough, were cumbersome, at best, to use. You had to constantly fetch the latest version from Code Vault, and searching was difficult – especially when multiple documents were involved.

• The Word documents did not contain many links, because links are so difficult to work with in Word (and cross-document links are essentially impossible).

• Many of the Word documents were huge, monolithic tomes – a thorough treatment of the topic, but difficult to work with. For example, you can't have multiple "pages" in the same Word doc open at once.

• The Word documents were not easy to view on mobile devices.

• Overall, the old system's cumbersome nature and rough presentation gave a negative impression, especially (but not only) to interns and new hires.

Sage improves on the old system in several ways:

• Sage is a web-based wiki system – bring your own web browser, open articles in different tabs, share links, make bookmarks, open Sage on your phone (even when not logged into the First Trust VPN).

• Sage is a centralized resource for programmers (and others) at First Trust. It offers a search feature that covers all Sage content.

• Sage has a modern user interface, inspired by popular websites such as:
  • https://developer.mozilla.org/
  • https://docs.microsoft.com/
  • https://docs.swift.org/
  • https://www.w3schools.com/
  Naturally, Sage offers ☼ light and ☾ dark themes (this was another weak spot for the Word docs).

• Refreshing Sage content is as easy as hitting F5 in your web browser. With the Word docs, you had to close Word, fetch the latest from Code Vault (to the correct folder), and re-open the document (and then pick up where you left off).

The Enterprise team no longer plans to use Word documents to document our tools and libraries.

However, Guru will still play an important role. Sage is the new home for documentation, but Guru is still useful for…

• Announcements, including: new features, deprecated features, bug fixes, enhancements, deployments, etc.

• Requests for, and discussion of, production database changes, database restores, etc.

• Meeting announcements and minutes.

• Questions and answers – though the answers will not contain much if any technical information (instead, we will link to relevant Sage articles).

Even though Sage is an Enterprise-created solution to an Enterprise-created problem (i.e., Guru and our Word docs), we welcome other departments to write their own documentation in Sage. The more this happens, the more of a centralized system we can offer – this is especially nice for on-boarding new hires, and for making a good impression on interns.

The Enterprise team did consider using an existing wiki-style documentation system. However, none of these systems would allow us to syntax highlight code examples the way we're used to. We have too many important programming languages at First Trust, including:

• Delphi
• SQL (with VDB function escapes)
• Fluent SQL
• MiniCalc
• DSConfig Files
• Delphi Forms (*.dfm)
• Guru
• DSP Classic

Losing the ability to highlight these languages was concerning. We knew we needed a better approach than Guru + Word docs, but the prospect of the new system looking worse than the old one, in this rather important area, became a deal-breaker in the end.

We also looked into using Markdown, but the same syntax highlighting issue prevented us from using it.

Instead, we developed Sage, with inspiration from Markdown (and several other languages with a similar purpose), and gave it the modern polish that the old system lacked.

Other benefits to developing our own system include…

• We host Sage here at First Trust, so we don't have to worry about downtime caused by technical issues at some third-party hosting service.
• We don't have to worry about whether Sage will continue to be supported down the road.
• We don't have to worry about poor support from some third party. This is more of a concern than you might think: we are so unhappy with IBM's support of both Informix and Maestro that we abandoned ship from the former, and are in the process of doing so for the latter.
• We can fix bugs and/or make enhancements, without waiting for an outside team.
• We can make sure that Sage integrates with our other tools, such as Code Vault, Shadowfax, Orion, and so forth.
• We have complete control of Sage, and can build whatever features seem important for First Trust.

We're quite happy with the end results, and we hope you are too!

We are aware of tools that automatically create documentation from source code. Sage doesn't currently work this way. If you're curious, you can read why here.