PAN.dev and the Rise of Docs-as-Code
It started out as a simple idea — to improve the documentation experience for the many open-source projects at Palo Alto Networks. Up until that point (and still to this day) our open source projects were documented in the traditional fashion: the ubiquitous README.md and the occasional Read the Docs or GitHub Pages site. In truth, there is nothing inherently “wrong” with this approach but there was a sense that we could do more to improve the developer experience of adopting our APIs, tools and SDKs. So began our exploration into understanding how companies like Google, Microsoft, Facebook, Amazon, Twilio, Stripe, et al., approached developer docs. Outside of visual aesthetics, it was clear that these companies invested a great deal of time into streamlining their developer onboarding experiences, something we like to refer to as “time-to-joy.” The hard truth was that our product documentation site was catering to an altogether different audience and it was evident in the fact that features like quick starts (“Hello World”), code blocks, and interactive API reference docs were noticeably absent.
After some tinkering we had our first, git-backed developer portal deployed using Gatsby and AWS Amplify, but that was only the beginning.
Great Gatsby!
Circa March 2019. Although we technically weren’t new to Developer Relations as a practice, it was the first time we made an honest attempt to solve for the lack of developer-style documentation at Palo Alto Networks. We quickly got to work researching how other companies delivered their developer sites and received a tip from a colleague to look at Gatsby — a static-site generator based on GraphQL and ReactJS. After some tinkering, we had our first git-backed developer portal deployed using AWS Amplify, but that was only the beginning. It was a revelation that git-backed, web/CDN hosting services existed and that rich, interactive, documentation sites could be managed like code. It wasn’t long before we found Netlify, Firebase, and, eventually, Docusaurus — a static-site generator specializing in the documentation use case. It was easy to pick up and run with this toolchain as it seamlessly weaved together the open-source git flows we were accustomed to with the ability to rapidly author developer docs using markdown and MDX — a veritable match made in heaven. We had the stack — now all we needed was a strategy.
At a deeper level, it’s a fresh, bold new direction for a disruptive, next-generation security company that, through strategic acquisitions and innovation, has found itself on the doorsteps of the API Economy.
For Developers, by Developers
At the surface, pan.dev is a family of sites dedicated to documentation for developers, by developers. At a deeper level, it’s a fresh, bold, new direction for a disruptive, next-generation security company that, through strategic acquisitions and innovation, has found itself on the doorsteps of the API Economy (more on that topic coming soon!).
The content published on pan.dev is for developers because it supports and includes the features that developer audiences have come to expect, such as code blocks and API reference docs (and dark mode!):
It’s by developers since the contributing, review and publishing flows are backed by git and version control systems like GitLab and GitHub. What’s more, by adopting git as the underlying collaboration tool, pan.dev is capable of supporting both closed and open-source contributions. Spot a typo or inaccuracy? Open a GitHub issue. Got a cool pan-os-python tutorial you’d like to contribute? Follow our contributing guidelines and we’ll start reviewing your submission. By adopting developer workflows, pan.dev is able to move developer docs closer to the source (no pun intended). That means we can deliver high-quality content straight from the minds of the leading automation, scripting, DevOps/SecOps practitioners in the cybersecurity world.
So, What’s Next?
If we’ve learned anything, over the years, it’s that coming up with technical solutions might actually be the easier aspect of working on the pan.dev project. What can be more difficult (and arguably more critical) is garnering buy-in from stakeholders, partners and leadership, while adapting to the ever-evolving needs of the developer audience we’re trying to serve. All this while doing what we can to ensure the reliability and scalability of the underlying infrastructure (not to mention SEO, analytics, accessibility, performance, i18n, etc.). The real work has only recently begun and we’re ecstatic to see what the future holds. Already, we’ve seen a meteoric rise in monthly active users (MAUs) across sites (over 40K!) and pan.dev is well-positioned to be the de facto platform for delivering developer documentation at Palo Alto Networks.
To learn more and experience it for yourself, feel free to tour our family of developer sites and peruse the GitHub Gallery of open-source projects at Palo Alto Networks.
For a deeper dive into the pan.dev toolchain/stack, stay tuned for part 2!
