|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|
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.
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 this duplication?
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 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.
||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?||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.||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.||Make Audacity more attractive to new developers||Do some kind of analysis of the likely cost/benefit of such a project.|
It is overload to tell users everything about each feature.
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
'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.
"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 CDThat'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 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
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
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.