The re-design of the OpenSIPS Documentation

The OpenSIPS documentation was designed and structured more than 15 years ago. The documentation covers a vast area – the generic manual, core documentation, module’s documentation, tutorials, migration docs, tips and more.

So there is a lot of content, currently sitting on top of mixtures of:

• formats ( wiki, html, xml)
• storing ( files on local FS, GIT repo)
• access (via GitHub, via pmwiki, no access)

And it is high time we got all of the above fixed and modernized.

Key objectives

When re-designing the entire documentation around the OpenSIPS project, several strong requirements were considered:

• using a new modern powerful format for the documentation
• keeping documentation in a resilient, shared storage
• providing easy access to any contributor to the documentation
• a unified approach for the entire documentation
• strong version correlation of the documentation with the code

The re-design

Well, after spending some time on research and evaluation different options, here is the outcome

The entire OpenSIPS documentation to use the Markdown (.md) format – this is format with a good ration between simplicity and how powerful it is. And it is also widely adopted.

Also the decision was taken to store the entire documentation on GIT repositories, on GitHub – which is markdown friendly :). This will give the desired resilience and collaborative work support.

Hosting the documentation on GIT with GitHub will allow access to anyone looking to contribute to the documentation. GIT pull requests via GitHub are a very easy and well known mechanism to contribute. In the past, the contributions were possible only the module’s documentation, leaving a large segment of the documentation locked for outside contributions.

Using GIT – the actual OpenSIPS GitHub repository, allows us to keep strong correlation between the code and the documentation. Whatever code is changed, in the same commit you should also address any documentation updates. And this works whether we’re talking module’s documentation or core documentation (variables, functions, parameters).

And yes, all the above are applied to the entire OpenSIPS documentation, no exceptions.

The content

Besides the format and structure, we took the challenge to work on improving and enhancing the content too.

The key objectives:

• bring everything up to date, matching the 4.0 version
• add as many full working config samples, for various scenarios
• trim what is obsolete/deprecated or what is of an interest.

The Manual pages were updated to the latest version. And for all the older version, the syntax and capability differences were checked and fixed.

The Advanced Tutorials pages were also brought up to day, migrating all the tutorials to the latest OpenSIPS version. They are now a great source of inspiration, considering that we added full working config files for many of them.

For the module’s documentation a large number of full working config files were added to show scenarios related to using that particular module from the OpenSIPS config file – again, these samples are a great source of inspiration.

The structure of the documentation

We are using multiple GIT repositories for the documentation, allowing better access control and sync with the code:

• the Manual part of the documentation (module’s docs, scripting, core functions and variables), which is strong related to the OpenSIPS version is now hosted in the same GIT repository as the OpenSIPS code.
• the documentation which is not sensitive to the OpenSIPS version, like the Advanced Tutorials, the Migration pages, etc, are located under a new separated GIT repository – nevertheless, it is also public and accepting contributions.

What is left

At this moment, we just did a hard replacement of the entire “documentation” section of the OpenSIPS site. This section is hosted on a different web server, with a different technology and engine.

To keep all the former documentation URL’s still alive, we set in place a strong set of HTTP redirect rules, to guide you to the new documentation pages.

What is left is to migrate the rest of the OpenSIPS website (non-documentation related) to the same concepts as for the documentation. This will result in a complete re-work and replacement of the OpenSIPS web site. The documentation section was the first and the most challenging one 🙂

In the meanwhile, please let us know of any issues resulted from this documentation migration and of course, we encourage you all to help us (via GIT Pull Requests) to improve and extend the OpenSIPS documentation !!

---