Rethinking the Manual

Forum-related announcements, polls, et al.
LWinterberg
Forum Staff
Posts: 211
Joined: Thu Jul 22, 2021 1:00 pm
Operating System: Windows 10 / 11

Rethinking the Manual

Post by LWinterberg » Thu Nov 18, 2021 1:09 pm

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 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, either as a reply here, or in the #new-manual channel on https://discord.gg/audacity
Audacity Team member (support & design - not a programmer)
Need help? Check Audacity Support and the manual!

steve
Site Admin
Posts: 85792
Joined: Sat Dec 01, 2007 11:43 am
Operating System: Linux *buntu

Re: Rethinking the Manual

Post by steve » Thu Nov 18, 2021 2:15 pm

LWinterberg wrote:
Thu Nov 18, 2021 1:09 pm
As a result, around 90% of Audacity users were using web search engines such as Google to get help with Audacity
and how many of those searches lead to the manual, or to a forum post with a link to the manual, or to an article derived from the manual?

Trying a few very common questions on Google:
gsearch1.png
gsearch1.png (61.15 KiB) Viewed 125728 times
gesearch2.png
gesearch2.png (97 KiB) Viewed 125728 times
gsearch3.png
gsearch3.png (68.17 KiB) Viewed 125728 times
Learn more about Nyquist programming at audionyq.com

steve
Site Admin
Posts: 85792
Joined: Sat Dec 01, 2007 11:43 am
Operating System: Linux *buntu

Re: Rethinking the Manual

Post by steve » Thu Nov 18, 2021 2:20 pm

LWinterberg wrote:
Thu Nov 18, 2021 1:09 pm
the average manual page about 180 clicks per month
I assume that you are referring to the online manual only (ignoring the tens of millions of people that have the manual installed locally).

What are the figures for the most visited pages, and which pages are they?
Are you getting figures from Cloudflare's cache or from the Audacity server logs, or somewhere else?
Learn more about Nyquist programming at audionyq.com

steve
Site Admin
Posts: 85792
Joined: Sat Dec 01, 2007 11:43 am
Operating System: Linux *buntu

Re: Rethinking the Manual

Post by steve » Thu Nov 18, 2021 2:26 pm

LWinterberg wrote:
Thu Nov 18, 2021 1:09 pm
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.
but extremely annoying for users when the "gospel of truth" (the manual) either does not know, or is wrong (as happened to me recently when I needed to know how to join two mono tracks to create a normal stereo track - spoiler: you can't.)
Learn more about Nyquist programming at audionyq.com

steve
Site Admin
Posts: 85792
Joined: Sat Dec 01, 2007 11:43 am
Operating System: Linux *buntu

Re: Rethinking the Manual

Post by steve » Thu Nov 18, 2021 2:29 pm

LWinterberg wrote:
Thu Nov 18, 2021 1:09 pm
In addition to written content, the manual should prominently be accompanied by video tutorials when appropriate.
That would be terrific :D

LWinterberg wrote:
Thu Nov 18, 2021 1:09 pm
We intend to encourage the already large video tutorial community to create content that fits in with the task-focused structure of the manual.
Good luck with that. Our past experience trying to do that has been disappointing. It would be great if you can get that to work. Perhaps Tantacrul's engagement on YouTube could provide some leverage.
Learn more about Nyquist programming at audionyq.com

steve
Site Admin
Posts: 85792
Joined: Sat Dec 01, 2007 11:43 am
Operating System: Linux *buntu

Re: Rethinking the Manual

Post by steve » Thu Nov 18, 2021 2:39 pm

LWinterberg wrote:
Thu Nov 18, 2021 1:09 pm
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.
Human translators or machine translation?

Human translations tend to be much better, but of course they rely on having people to put the hours in on a regular basis to keep it up to date.
Learn more about Nyquist programming at audionyq.com

steve
Site Admin
Posts: 85792
Joined: Sat Dec 01, 2007 11:43 am
Operating System: Linux *buntu

Re: Rethinking the Manual

Post by steve » Thu Nov 18, 2021 2:47 pm

@ LWinterberg, what are your thoughts about 3rd party resources? For example, there are already a lot of Audacity tutorial on YouTube, and a few of them are quite good. Are you considering making use of 3rd party resources, or keeping the "official" documentation in-house?
Learn more about Nyquist programming at audionyq.com

LWinterberg
Forum Staff
Posts: 211
Joined: Thu Jul 22, 2021 1:00 pm
Operating System: Windows 10 / 11

Re: Rethinking the Manual

Post by LWinterberg » Thu Nov 18, 2021 4:22 pm

steve wrote:
Thu Nov 18, 2021 2:15 pm
LWinterberg wrote:
Thu Nov 18, 2021 1:09 pm
As a result, around 90% of Audacity users were using web search engines such as Google to get help with Audacity
and how many of those searches lead to the manual, or to a forum post with a link to the manual, or to an article derived from the manual?
Surprisingly little unfortunately. Depends on the example, of course - in general, the FFMPEG stuff and some of the common tutorials do fairly well, but the current structure also causes some very important things to be fairly hidden. For example, if you search for some variation of adjusting recording volume, you'll generally find other results and our "Making a test recording" tutorial. While that contains the information wanted, it also is titled in a way that doesn't match what the user is searching for and gets rather terrible CTR and ranking on it from Google (2%, 10th result), and I don't think I've managed to find a related search query that even makes the "real" article on the feature (Mixer Toolbar) show up at all. For comparison, the FFMPEG for windows page ranks first and has a 65%+ CTR depending on the search page.

This video alone outperforms the entire manual combined if it wasn't for the "installing FFMPEG on Windows" article.
steve wrote:
Thu Nov 18, 2021 2:20 pm
LWinterberg wrote:
Thu Nov 18, 2021 1:09 pm
the average manual page about 180 clicks per month
I assume that you are referring to the online manual only (ignoring the tens of millions of people that have the manual installed locally).
I ran a survey on that this summer - 90% use Google or other search engines, only 10% use the help menu, and 6% use the ? icons (numbers go >100% because you could select multiple responses). So while it's true there's some offline manual use which I don't know anything about, I do know that it's definitely the minority of users.
steve wrote:
Thu Nov 18, 2021 2:39 pm
LWinterberg wrote:
Thu Nov 18, 2021 1:09 pm
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.
Human translators or machine translation?

Human translations tend to be much better, but of course they rely on having people to put the hours in on a regular basis to keep it up to date.
I was thinking human translations, and hope there is interest in doing this. I hope that keeping the translations up-to-date will be easier with tools such as Transifex.
steve wrote:
Thu Nov 18, 2021 2:47 pm
@ LWinterberg, what are your thoughts about 3rd party resources? For example, there are already a lot of Audacity tutorial on YouTube, and a few of them are quite good. Are you considering making use of 3rd party resources, or keeping the "official" documentation in-house?
I'd like to have third party resources in. I think there will need to be some requirements for them which I listed out here - though as anything there, that's just my initial thoughts. I'm happy to be convinced to be more (or less!) strict with the rules :)

That said, I expect there to be some in-house stuff as well, particularly for new features and such.
Audacity Team member (support & design - not a programmer)
Need help? Check Audacity Support and the manual!

steve
Site Admin
Posts: 85792
Joined: Sat Dec 01, 2007 11:43 am
Operating System: Linux *buntu

Re: Rethinking the Manual

Post by steve » Thu Nov 18, 2021 4:58 pm

LWinterberg wrote:
Thu Nov 18, 2021 4:22 pm
I ran a survey on that this summer
I bet the pre-2016 Brexit Referendum surveys were a lot bigger, but they were all wrong ;)

We have never had the resources to do SEO for the manual, but if you have the resources then that would clearly provide a good ROI. "Some guy on YouTube" should not be coming higher than the official documentation.
LWinterberg wrote:
Thu Nov 18, 2021 4:22 pm
This video alone outperforms the entire manual combined
and clearly that is SEOptimized, and possibly boosted by Google for its ad content.

LWinterberg wrote:
Thu Nov 18, 2021 4:22 pm
I think there will need to be some requirements for them which I listed out here - though as anything there, that's just my initial thoughts.
Looks like a good start, though I suspect that those making the more professional videos (such as your example above) may prefer to optimize for ad$ (such as placing adverts / sponsorship at the start). It would be terrific if some talented video makers are happy to put "benefit to the Audacity community" ahead of financial reward, but that seems to be increasingly rare these days.
Learn more about Nyquist programming at audionyq.com

waxcylinder
Posts: 15387
Joined: Tue Jul 31, 2007 11:03 am
Operating System: Windows 10 / 11

Re: Rethinking the Manual

Post by waxcylinder » Thu Nov 18, 2021 5:07 pm

LWinterberg wrote:
Thu Nov 18, 2021 1:09 pm
...
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.
Yes, ensuring the accuracy and completeness of the manual did sometimes slow down release cycle a little at times (but not always).

We (old Team) used to regard the up-to-dateness of the manual at release as part of the quality control and quality assurance process. Checking the functionality of new and changed features in order to fully and properly document them helped to ensure that things were as they should be as as they were intended to be,

If major changes are made early on in a dev cycle then it is comparatively easy to get the manual properly up to date long before release candidates are considered. But if major changes are made late on (for example the latest looping changes) that is harder to achieve without delaying a release.

Peter.

Post Reply