GSoD Ideas

From Audacity Wiki
Revision as of 19:14, 16 April 2019 by James (talk | contribs) (Top Issue)
Jump to: navigation, search
Google Season of Docs (GSoD) is Google's program for promoting Open Source Software documentation.
This page contains our ideas for suitable projects for 2019
Related article(s):



Based on our experience in GSoC, we *expect* incremental work, with agreed frequent check ins to GitHub (or similar) of work in progress - with work that is ready enough that your mentor can give useful feedback. In return, mentors will be available to guide and give feedback.

  • We work by email, not IRC nor video chat. It's what works for us.

Project Definition

We have several seed ideas for this years GSoD.

  • For a seed idea to become an active project it must:
    • have clear benefits
    • be well defined
    • be achievable in the time

Seed Project Ideas

Name Difficulty Idea High Level Benefit Show us you can...
Information Architecture
(Our Top Issue)
Moderate Our documentation is organised as a reference. It has ended up with quite some duplication - because there are multiple ways to organise the features.
We organise the features by the menu items that invoke them, by the toolbars (which do so too) and thematically. Also we have summary pages and detail pages. There tends to be duplication between these. How can we better reduce or at least manage this duplication?
  • ToDo.png Analyse the problem, and highlight key duplication problems.
  • ToDo.png Propose an approach to fixing the problem.
  • ToDo.png Sample of pages showing how to make the changes.
  • ToDo.png Guidelines for future writers to avoid duplication in the first place - "What should/should-not be on this page?"
'Tighter' clearer manual. Show us an Information Architecture you have done for someone else, and describe something of how it is does and does not match our needs.
"How do I?" docs Moderate Our documentation is organised as a reference. However, most users come to the documentation with a specific question or issue to solve. Some of these are covered in our FAQ. Some of the common tasks are covered in our tutorials and our getting started guide. We think there is a 'long tail' on these kinds of docs. We are potentially able to write docs for the most common issues that affect 80% plus of users. However we don't have the resources to write tutorials on "Tips for placing microphones for a piano" and all the how-to docs that could be asked for, so we would like a clear way for where to draw the line similar to The pokemon Test. We also have a problem in that the 'How Do I' documents may duplicate content. We'd like, mostly, to refer to docs rather than re-present the same information.
  • ToDo.png Are our existing 'How Do I' docs sufficiently easy to find? If not, how do we fix the 'finding' problem?
  • ToDo.png Analyze the choice of content, level and organisation of these docs, and highlight key problems.
  • ToDo.png Propose an approach to fixing the problems.
  • ToDo.png Sample of pages showing how to make changes to 'How Do I' docs.
  • ToDo.png Guidelines for future writers - "What principles help us with 'How Do I' document scope?"
More relevant and more useful tutorials. Edit / reshape one important tutorial we already have.
Navigation in Manual and Wiki Moderate The sidebar in our manual is already quite long. Some topics are handled in our wiki, some on our forum. We also have tables, categories and links. How can we better organise the navigational structure so that users can find what they are looking for?
  • ToDo.png What are users looking for?
  • ToDo.png Are there important gaps in the top ten topics?
  • ToDo.png Review navigational structure and recommend changes.
Users can find the relevant documentation more easily. Help us (work with us) to prepare a survey to users about what they need.
Video! Hard Books and written documentation appeal to older users. Younger users 'expect' youTube videos. Video is also relevant with dyslexia. Media production software like Audacity should be catering for dyslexics.
  • ToDo.png Review the ideas for making maintainable videos which don't go out of date with each new release.
  • ToDo.png Choose some big-win videos, and make them.
  • ToDo.png Plan
Reach more users with help by providing information in an audio-visual format Find / Watch several popular youTube Audacity videos, and tell us what makes them popular.
For Developers Hard We have automatically produced dOxygen documentation that is based on comments in our source code. We also on our wiki have a developer section and there are docs (in GitHub) on compiling that refer to more detail in the wiki. A frequent comment from participants in GSoC was that more documentation on the structure of Audacity in the parts relevant to their projects would have helped.
  • ToDo.png Identify where there might be big wins in documentation for developers.
  • ToDo.png Work with active developers to produce such documentation.
Make Audacity more attractive to new developers Do some kind of analysis of the likely cost/benefit of such a project.

Information Architecture

It is overload to tell users everything about each feature.

Example Problem:

There are a myriad ways of selecting audio..

  • By drag to select
  • Using the Select button in the track control panel
  • Using Ctrl-A keyboard shortcut
  • Using a label
  • Using the selection toolbar
Further there are special kinds of selection, such as spectral selections which selects frequencies, not just times. And there are ways to modify a selection after creating it.

'How Do I?' Docs and Tutorials

Getting started with Audacity is a major hurdle for many of our users. Although we do have some tutorials, many of them require jumping from one section of the manual to another, and then finding your way back to move onto the next part.

Example Problem:

"I just want to record a radio show and put it on CD so I can listen to it in the car", will take you to:

Tutorials > Recording audio playing on the computer
> Recording Computer Playback on Windows
> Windows Control Panel for sounds
< Recording audio playing on the computer
> Export Audio
< Recording audio playing on the computer
> Recording and Editing
Home page > Copying tapes, LPs or MiniDiscs to CD
That's a heck of a lot of information for a new user to take in.

Our FAQ misses quite a lot of common issues, so as to avoid the page becoming too long.

Example Problem:
Example of a common issue missed by our FAQ

Perhaps we could provide better coverage if we made use of FAQ / Q&A software. Some examples:


Example Problem:
We still don't have a searchable manual for users.

We can use a script to produce a PDF version of the manual, and that has a contents page and index. However, the PDF version needs significant work to look professional. It is more 'proof of concept' at this stage, showing that we can transfer all the image maps and hyperlinks of the html version into pdf format. Note that Adobe Acrobat does not offer this functionality. It needs our script.

Video and Other Formats

Example Problem:
Although anyone working on an Audacity project will be on a laptop or Desktop machine, it could be useful for some if the manual was mobile friendly. It would then be possible to refer to the manual on a phone or tablet, while having Audacity full screen on the computer.

For Developers