Difference between revisions of "GSoD Ideas"

From Audacity Wiki
Jump to: navigation, search
(architectural problem is deeper.)
(Clearer.)
 
Line 31: Line 31:
 
| style="background-color:#dcdccb;" | Information Architecture<br>''(Our Top Issue)''
 
| style="background-color:#dcdccb;" | Information Architecture<br>''(Our Top Issue)''
 
| style="background-color:#eeeecc;" | Moderate
 
| style="background-color:#eeeecc;" | Moderate
| style="background-color:#eeeecc;" | Our documentation is organised as a reference.  It has ended up with quite some duplication - because there are multiple ways to organise the features.<br>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 this duplication?
+
| style="background-color:#eeeecc;" | Our documentation is organised as a reference.  It has ended up with quite some duplication - because there are multiple ways to organise the features.<br>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}} Analyse the problem, and highlight key duplication problems.
 
* {{todo}} Analyse the problem, and highlight key duplication problems.
 
* {{todo}} Propose an approach to fixing the problem.
 
* {{todo}} Propose an approach to fixing the problem.
* {{todo}} Sample of pages showing how to make the changes.
+
** {{todo}} Sample of pages showing how to make the changes (correction example)
 +
** {{todo}} List of ALL pages and notes for each on what needs to move (correction plan)
 
* {{todo}} Guidelines for future writers to avoid duplication in the first place - "What should/should-not be on this page?"
 
* {{todo}} 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.
 
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.
  
 
| style="background-color:#dcdccb;" | 'Tighter' clearer manual.
 
| style="background-color:#dcdccb;" | 'Tighter' clearer manual.
| style="background-color:#eeeecc;" | 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.
+
| style="background-color:#eeeecc;" | Show us an Information Architecture you have done for someone else, and describe something of how it does and does not match our needs.
 
|-
 
|-
 
| style="background-color:#ccccbb;" | "How do I?" docs
 
| style="background-color:#ccccbb;" | "How do I?" docs

Latest revision as of 07:59, 17 April 2019

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):



Projects

Communication

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. 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.


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: https://www.findbestopensource.com/tagged/faq

Navigation

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