User:James/Documentation2 Project

From Audacity Wiki
Jump to: navigation, search
The 'Documentation2 Project' is a project to make documentation for people who work on and develop audacity. Its intention is to make it that bit easier for new code contributors to get involved with Audacity.

We have extensive documentation for users.

This project looks at the second side, progressing documentation for contributors and potential contributors. It would bring code and algorithm documentation to a higher level. The project is about 2/3rds researching and writing of content, and 1/3rd coding.

The project started on 26th May 2018 is still at the proposal stage.


Strategy

Developers getting involved in working on Audacity code have said there is a major lack of documentation for the code and that this makes working with the code hard. However, documenting Audacity for developers is a lot of work. It could be as much work as documenting Audacity for users. Although it benefits a far smaller number of people, if it brings in new developers to Audacity, or makes it more enjoyable for current developers, it's worth doing.

How can we do it in a way that is maintainable and not as much work as maintaining the manual?

For developer documentation to work, we have to:

  • Automate what we can. (reduce workload)
  • Integrate with in-code documentation i.e. the comments in code, including the structured comments for Doxygen. (stay up to date, in sync with the code)
  • Integrate with QA related information, mostly Bugzilla. (reduce/share the work with work that has to be done in any case)

There are two main strands in this development:

  1. Extend WIT in ways that are useful to developer documentation AND to normal user documentation AND to QA. One particular detail is to make the interactive style of diagrams in WIT, and their future developments, available within the online wikis using a wiki extension. Offline manual would continue to have static images. Technically this is not hard - it is just inclusion of part of one web page in another. We'll want to adapt the diagrams somewhat to integrate nicely.
  2. Rather than document places where existing design in Audacity is sub-par, change Audacity to make the documentation easier to do. This will have direct benefits for Audacity itself. An initiative to improve code documentation will have a direct benefit improving code quality, making Audacity code easier to work with. That code quality benefit is not just a nice to have. The more orthogonal our code is, the more we can do with less code.

The documentation2 project has deliberate limitations over what could be produced, to keep the project in bounds. It isn't going to re-write Audacity, just organise some parts of the code 'better'. The focus in refactoring is on the smaller changes that deliver the most benefit for the work done.


Planned 'Deliverables'

Dynamic 'Full Release Notes'

Dynamic searchable release notes list.
  • This will use release-notes text extracted from Bugzilla, and display it in WIT.

RelNotesWordle.png
A Wordle - One idea for a fancy-pants keyword search


The current release notes, listing all P3 bugs, are intimidating and they are hard to navigate. The proposed feature is a dynamic release notes page. It's a keyword search, done rapidly in the user's browser, by sorting the list.

  • No need to use the Catalase conversion page to format release notes.
  • WIT would provide a list, dynamically sorted.
    • The page by default shows P2 issues only (less intimidating), but you can click 'Show All'
    • Typing words into the search box organises the results, most relevant at the top.
    • Words that match bugs in several categories are no longer a problem.
  • The page has some suggested 'search words' based on what we have experienced in support.
    • These suggested search strings are in a 'Wordle' and clickable.
Bulb icon This search system can later be repurposed for other information, if we want to do that


Wiki Developer Docs

More wiki-docs written for developers
  • This is the main task in the project, and other tasks help advance it.
  • Our existing developer documentation is rather sketchy. This gets it properly started.


Develop.png
Extend our existing on-wiki Developer Documentation


Extend write up of existing developer topic docs for our wiki

  • Introduction to digital audio dyn-diag
  • Introduction to spectrograms dyn-diag
  • Writing Nyquist Plug-ins
  • AudioIO dyn-diag
  • Blockfiles / SQLITE dyn-diag
  • Waveform rendering
  • Effects
  • Commands
  • The TrackPanel
  • Load and Save (including auto-save / recovery)
  • Undo / History

New developer topic docs for our Wiki, (with help from other team members on sticky details).

  • Overview of Audacity Classes dyn-diag
  • Overview of How Audacity is Developed dyn-diag
  • Noise Reduction Algorithm
  • Spectral Refinement Algorithm
  • Repair Effect Algorithm
  • Inside Nyquist


For-Developer Diagrams

Extend the kind of diagrams that can be produced automatically or semi-automatically

The items marked with a dyn-diag in 'Wiki Developer Documentation' are the ones most likely to gain new dynamic diagrams.

  • At least four new diagrams.
  • WIT will host these diagrams, and image-link to actual code in Doxygen. They can also be used as static diagrams in wiki.
  • Other new diagrams for WIT, to cover Audacity preferences and other Audacity track types to waves.

Architecture.png
Diagrams can show other aspects of Audacity Architecture and Algorithms


Doxygen can produce GraphViz based hierarchy information. I plan to investigate other ways to present additional structural information.

  • The diagrams will accompany topics in the wiki doc.
  • Some of the diagrams will be hover-over image-map or interactive in other ways, when used in WIT.


WIT currently is based on the front-page of the manual, which shows a WaveTrack and a LabelTrack. Whilst doing the new diagrams I will also add dynamic screenshot image-maps for:

  • All 19 preference panels
  • A MIDI track view
  • Envelopes on WaveTrack
  • Clips on a WaveTrack (Split-Delete)
  • Spectrogram on WaveTrack (including Spectral Selection toolbar)


Classes Doxygenated

Doxygen class list completed.
  • Our class list is currently about half complete.

Doxygenated.png

Complete the Doxygen class list

Currently our doxygenation of Audacity has a lot of holes in the class list. Completing the class list doxygenation is one of the deliverables.


Code Refactorings

Code Structure work.
  • Making the code more logical will make it easier to explain.

DoxyGraphWiz.png
Refactorings to get more logical class structures


I will make some code and class refactorings and renamings to make the Doxygen structure of Audacity cleaner and clearer.

  • Changes to move ShuttleGui towards being declarative.
  • Introduction of a Registrar class, to unify the registration and 'dictionary manager' mechanisms.



WIT Additions

Improvements to WIT.
  • Images-Mapped images direct from WIT, to reduce the steps in keeping images up to date in manual.
  • Add keyboard image-map to WIT
    • This is a nice to have, and helps progress automatic image generation.
  • Support arbitrary shaped image-map elements in WIT

KeyboardImage.png
Manual would gain a clickable Shortcuts-keyboard image-map


I will add an auto-generated WIT image map that maps keys on a (standard 101 UK and US keyboard) to their default function.

  • Also can be used as an image map in the manual.


Media-wiki has the ability to transclude images from white-listed sites. If we do that for WIT, the static images become directly available to manual without additional steps to transfer them.