Introducing the Passenger Library project

We are happy to announce the Passenger Library project: next-generation documentation for the Phusion Passenger application server.

For a while now, we have had the feeling that our documentation was getting old. The content has always been kept up-to-date, but aspects like the presentation & navigation have become outdated. The audience has become wider, causing the documentation to contain a lot of information that may not be relevant to the current reader.

We strongly believe that high-quality documentation should be part of any high-quality software product. For this reason, we embarked on an ambitious journey two months ago: to completely overhaul the documentation.

The Passenger Library is about 70% done now, and is in a good enough state to be announced publicly. In this article we will explain what was wrong with our old documentation, why we felt that it was necessary to rework it, and how the new documentation (the Passenger Library) is better. In particular, the Library is not only written to be beginner-friendly, but also to be valuable to intermediate and advanced readers, featuring both simple walkthroughs as well as advanced guides for scaling, high availability, monitoring and Passenger internals.

What's wrong with the old documentation?

The old documentation, in particular the Passenger + Nginx manual, Passenger + Apache manual, and Passenger Standalone manual, suffer from the following problems:

• It assumes intermediate/advanced development and Unix skills
  
  The structure assumes that the reader has intermediate/advanced skills in their programming language (Ruby, Python, Node.js), as well as in Unix and system administration. As such, the documentation doesn't go too deep into certain topics, such as Unix permissions, environment variables, etc. It is assumed that the user is skilled enough to know how to deal with those things.

  This was a reasonable assumption when Passenger was first introduced, but is no longer reasonable today. Over the years, we have encountered more and more support requests about basic Unix system administration or basic language-specific tooling like Bundler.

• It assumes basic Nginx/Apache skills
  
  The structure assumes that the reader has basic Nginx/Apache skills, such as how to operate and configure Nginx/Apache and how to install Nginx/Apache modules.

  Again, this was a reasonable assumption Passenger was first introduced, but not anymore. We encounter more and more users who have never used Nginx or Apache, and/or do not know how to install and manage Nginx/Apache modules.

• Its scope is limited
  
  The old documentation is focused on Passenger only. It does not cover indirectly related topics such as installing, configuring and operating Nginx/Apache; scaling; high availability; etc. But in recent years we have noticed more and more demand for learning material on these topics.

• The book-like format is no longer appropriate
  
  Not only is our user base very diverse, their server configurations are also very diverse. Over the years, we have written a lot of use-case-specific documentation in order to be able to serve such a diverse audience. Since the old documentation is generated with Asciidoc, it follows a book-like format with chapters, sections and subsections. This format is increasingly problematic because it requires constant attention for navigating back-and-forth to find relevant sections.

  For example, in the Installation chapter of the manual, we have 5 sections that each cover a different operating-system specific installation method. We have seen that many readers get lost and confused because they have to skip over so much information that is irrelevant for them.

An evolutionary dead-end

Over the years, we have tried to address all these issues by adding more documentation and restructuring chapters. For example, we introduced an entire chapter devoted to explaining how environment variables work in Unix, and the entire Installation chapter has been rewritten at some point. But ultimately, the legacy writing structure and presentation format of the old documentation limited the potential improvements.

The Passenger Library

To update the existing, extensive documentation with newly emerged needs, it was necessary to take a step back and come up with a core redesign. The goal of the Passenger Library is to provide complete and comprehensive documentation, tailored to the individual reading it.

We've accomplished this by expanding the existing documentation set to be more complete for a wider audience (e.g. using walkthroughs and in-depth articles), while at the same time making it easier to spot relevant information (organized through a website-like format) and unobtrusive ways to filter out irrelevant items (selectors with memory).

The Library is designed to be beginner-friendly. Its structure walks through inexperienced readers from beginning to end, in an easy-to-follow tutorial format where they can experience success as quickly as possible. We've done our best to make the learning curve completely smooth. There is even add-on documentation to teach inexperienced readers about Unix basics, system administration basics, Nginx and Apache basics, etc.

All documentation is clearly categorized by programming language and integration mode, so that you will only be presented with the information relevant to you.

And the Library is not meant for beginners only. It is also very valuable to intermediate and advanced readers. Advanced topics such as scaling, high availability, monitoring and Passenger internals are also covered.

Open source and contributor-friendly

Finally, the Passenger Library is completely free and open, being licensed as Creative Commons BY SA 4.0.

We have also made contributing documentation a lot easier. The source is hosted on Github and written in plain Markdown and HTML. Every page has an "Edit" link that will allow you to directly contribute edits in the browser. Contributing a change is only a commit away!

Conclusion

We've put a lot of hard work into the Passenger Library. While the Library isn't fully complete yet, it is already more comprehensive than the old documentation. We hope that many of you find it valuable, and we encourage you to contribute any missing documentation.

What do you think of the Library? Please let us know by posting a comment below.