Online Technical Documentation based on WordPress
Recently, we were asked to implement an online technical documentation solution by one of clients. We had to move the existing offline documents (mainly MS Word and PDF files) to an online accessible format that would also allow the users to modify the documents by themselves. We thought about the following options for implementing this:
- Implement a custom web based ASP.NET solution, starting from scratch
- Use Wiki engine
- Use CMS (e.g. WordPress)
We did not choose the custom implementation because it was the most time consuming option. We also did not choose the Wiki software because we found it a bit outdated and too restrictive and finally we focused on the CMS solution.
After doing a short research we found that WordPress is actually a pretty good candidate to solve our problem. It is exactly what we needed:
- Online platform that allows preview/modification of various articles.
- It is very easy to use.
- WordPress is highly customizable –plenty of plug-ins out there.
- There is a great community which means frequent updates and a lot of discussions on various topics.
- WordPress has a support for tracking changes and revisions, which was one of the requirements.
- It is open-source and free.
It is important to notice that the system for which we had to prepare the online documentation tool is a web application built by using ASP.NET and SQL Server.
So, following are the different aspects of what we did to get the entire thing working.
Get WordPress running on a Windows server
Since our application is running on ASP.NET/IIS/SQL Server, we had to install and configure PHP and MySQL on a Windows environment. We got PHP running under IIS and we installed MySQL to host the WordPress database.
Create a custom theme in WordPress
WordPress is very flexible when dealing with branding. We created a new custom WordPress theme that matches the look and feel of our main web application. Also, we implemented a handy navigation pane that provides an easy way to browse the various articles.
Build a hierarchy of topics and documents
We had to build a tree-like hierarchy of the various technical documents. We found a WordPress plug-in called “CMS Tree Page View”. It is doing a great job organizing the pages in WordPress in a tree hierarchy. So, administrators of the technical documentation can easily organize the list of documents and also the end users are able to easily navigate through the content.
Integration with existing users
This is the toughest parts of the implementation. We had to integrate the users of the existing web application with WordPress. We used the “External Database Authentication Reloaded” plug-in which allows using an external database to authenticate the users who can access the WordPress site.
Our web application is based on Forms Authentication in ASP.NET and users are stored in SQL Server database. Passwords are hashed.
We configured the plug-in to use our existing SQL Server database and to hash the passwords in the same way as the main web application does. As a result, we succeeded to allow our existing users to access the WordPress documentation site by using their existing accounts.
Restricting site access
We integrated the WordPress authentication mechanism with our existing database but we also had to restrict the access to the “public” WordPress website, because that was the client’s requirement. He wanted it to be available only for authenticated users and we used the “Restricted Site Access” plug-in for that purpose.
Single Sign On
After we got WordPress running and working good with our existing users we had to fully integrate it with the main web application. We added links for the “documentation” website to our main ASP.NET application. But the two systems are really two different applications and users had to provide their credentials for each one of the two systems. This is frustrating and that is why we implemented Single Sign On. That means that once the user is successfully authenticated into the main web application then he is automatically authenticated into the WordPress website too.
We had to integrate some PHP code into our existing ASP.NET application. We did this by redirecting the user from the ASP.NET application to a special PHP file which is performing the WordPress authentication. Then the PHP file automatically redirects the user back to the main ASP.NET application. This happens automatically and it doesn’t affect the user experience with the main application.
The custom PHP code registers a new session in the WordPress site by calling the wp_set_auth_cookie() function.
WordPress is a great platform and it can be successfully integrated with other applications to serve as an Online Technical Documentation tool!