Hello
In this post, I want to introduce our plans to create a new online manual, which we intend to replace the current one found here.
First, it is worth explaining why we want to replace the existing manual, which has been meticulously kept up-to-date by a handful of dedicated contributors. The existing system is built on MediaWiki, which unfortunately comes with a lot of trouble attached that limits its overall usefulness: For example, due to spam problems, it has not been open to contributions from the public for a long time. As a result, the number of active editors has been very small (around 3 or 4 people). Consequently, it has also not been translated in quite a long time, which we feel is a big disadvantage.
Secondly, the manual was being packaged with the installer, which meant that it needed to be completely up-to-date prior to a release. Apart from being an unnecessary release blocker, this also meant that any corrections or optimisations to the manual could only be published whenever a new version of Audacity was released.
Thirdly, it was written to serve a dual-purpose: being both a developer reference as well as a user manual, which made it quite complicated – a problem exacerbated by not having a search function. As a result, around 90% of Audacity users were using web search engines such as Google to get help with Audacity, where more user-focused content from third parties massively out-performed our manual (the average manual page gets about 180 clicks per month). This is significantly lower than what we expect from an app as widely used as Audacity is.
For the above reasons, we have decided that our resources are overwhelmingly better spent on creating a new manual that attempts to get users up to speed as easily as possible. This new manual will be called Audacity Support.
With that in mind, we want to accomplish the following goals with Audacity Support:
- It should be user-focused. That means it should be easy to read and friendly, giving as much information as necessary to achieve a given task, without being either too vague or too detailed. It also should be search optimized, helping users to find what they’re looking for quickly.
- It should be continuously editable by anyone and not be a release-blocker anymore. Although this means that pages will sometimes be ‘out of date’ at the time of a new release (although we’ll seek to avoid that as much as possible), we feel it is a price worth paying to achieve the goal of a vibrant community of contributors and translators.
- In addition to written content, the manual should prominently be accompanied by video tutorials when appropriate. We intend to encourage the already large video tutorial community to create content that fits in with the task-focused structure of the manual. This would be a perfectly symbiotic relationship, since the manual will provide them an additional source of views.
- Crucially, Audacity Support will also be translatable. Mediawiki can do this with great effort, but we’d like to have a system that supports translations more easily.
- Readers should be able to search for content in Audacity Support itself, and be able to download a PDF version of it should they need access to an offline copy.
The current plan is to host Audacity Support on Gitbook. Gitbook has inherent benefits over MediaWiki for our purposes in several areas:
For Contributors, Gitbook has a nice visual editor (as opposed to MediaWiki’s plain-text/wiki-syntax editor). It also can sync to Github, so if you prefer working with a local markdown or text editor, you can do that, too. This Github integration also will enable translations down the line (several translation tools integrate with it easily), but since we’re starting fresh, we’ll hold off on translations until the English version has reached a somewhat decent level of maturity. Video tutorial creators will be able to easily embed their content on relevant pages.
There may be individual pages from the old manual which make sense to be ported over to Audacity Support, but generally, we want a fresh start, with the developer reference bits of the old manual not getting ported over. Speaking of which, the old manual would stay as-is and will not get updated or included in the installer past 3.1.x.
As a preview, you can view the Gitbook page on https://audacity.gitbook.io/audacity/. Please bear in mind that we have only just started the process of populating it with content and it still contains a lot of unfinished material. While we are not yet calling for contributions, you can get editor access on https://audacityteam.org/gitbook-access. We will welcome anyone who wants to take part in defining the overall structure and style.
We would be very interested to hear your suggestions on how we can make further improvements to this plan. You can send them in our Forum, or in our new discord server.
