From Audacity Wiki
Revision as of 07:29, 15 March 2019 by James (talk | contribs) (New category.)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search
Google Season of Documentation  (GSoD) is Google's experimental program for promoting Open Source Software documentation. GSoD is a companion project to Google Summer of Code  (GSoC).

Audacity hopes to be a pioneering mentoring organization for Google Season of Documentation 2019.

  • This table comes from GSoD Ideas where there is a discussion of how to interpret it.

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. So the same information can end up on three pages. Also we have summary pages and detail pages. The detail pages duplicate some of the information on the summary pages. How can we better reduce or at least manage all 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 (correction example)
    • ToDo.png List of ALL pages and notes for each on what needs to move (correction plan)
  • ToDo.png Guidelines for future writers to avoid duplication in the first place - "What should/should-not be on this page?"

We suspect the problem is deeper than presented here. The amount we need to say about each feature varies considerably. Thus in some cases it makes sense to group related features together. In others a feature needs a page to itself. This gives conflicting pulls as to how to organise the documentation.

'Tighter' clearer manual. Show us an Information Architecture you have done for someone else, and describe something of how it 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.


The following 2 pages are in this category, out of 2 total.