tenacity-legacy
tenacity-legacy copied to clipboard
tenacityteam
Tenacity's own manual
- [x] I have read the specified guidelines for issues
Describe the bug Tenacity links to the Audacity Manual and not a Tenacity Manual
To Reproduce Steps to reproduce the behavior:
- Help > Manual
- Click on link to online manual
- Observe: the Manual is the Audacity Manual
Expected behavior A Tenacity Manual
Screenshots Not applicable
Additional information (please complete the following information):
- OS: all OS
- Version Tenacity 3.0.4
Additional context This is important as Tenacity and Audacity are likely to diverge so you cannot necessarily rely on the Audacity Manual.
Not too that the app has many links to the manual from many dialogs (Prefs for example) and most error messages - via the "?" help button.
Nice catch; writing our own wiki is something we need to do in the near future, but I don't think it's that urgent.
If someone wants to set up the groundwork for documentation on tenacityaudio.org with Hugo or Jekyll, patches are welcome.
Nice catch; writing our own wiki is something we need to do in the near future, but I don't think it's that urgent.
If someone wants to set up the groundwork for documentation on tenacityaudio.org with Hugo or Jekyll, patches are welcome.
For a dev it's not that urgent right now. Once you ship for the user it will be. Best advised to have docs ready when the release ships. The Audacity wiki is CC so you can use that as a starting point. That way there will be a base from which to work and something when it ships.
Where the content physically resides on a server isn't as big a concern as having the content in the first place. As long as the docs are linked from the main page with an URl that is fairly repeatable and the docs have a good navigation structure it should present an issue. An important aspect is that it should present as a user manual and not a code repository.
There are advantages to using the existing infrastructure at the code repo sites as long as the content is geared toward the user.
We could also use man.sr.ht or github wiki for hosting.
I think man.sr.ht or GitHub Wikis are primarily designed for development information (building, configuring, hacking etc.). A URL like https://man.sr.ht/~tenacity/tenacity/ is much less inviting than https://tenacityaudio.org/docs/.
Although I absolutely understand the threadstarter, I also kind of agree with RoaddogLabs.
While high quality documentation/manuals is great, IMO to some extent a community can "workaround" in other ways - blogs, StackOverflow, IRC (kind of) and so forth. Not saying that this is not a good idea, but IMO it isn't as important as, say, seeing tenacity not lose out in the competition with audacity. The latter just released 3.0.3 - can't let the telemetry guys win! ;)
As for docs - I really love the documentation such as: https://python-gtk-3-tutorial.readthedocs.io/en/latest/
I forgot the name of the software, but I like that it can be read as a book. This may not always be appropriate (when you lack time for instance, it's not so good) but other than that I love that it is a "full explanatory" setup. This would be cool if you could e. g. aim at a newcomer, who may not know stuff, but is sufficiently clever to learn quickly when things are explained to that newcomer. So a medium-to-advanced tutorial. (I forgot which software this creates ... I think some python pypi software? There are other examples for this read-the-docs booklet styles such as https://fpm.readthedocs.io/en/latest/ ... ok so evidently it's at readthedocs but I think it is also available as some download on pypi ... at the least I think I saw it before ...).
As for Sphinx docs: I found them always ugly. But I don't want to divert about the style - the more important thing is that documentation for the end user is not forgotten in the long run. :)
As for Sphinx docs: I found them always ugly.
I think that the documentation listed does actually use Sphinx, but with Read the Docs' custom theme. Sphinx is a good base, because it is very configurable later down the line but you can get something simple out now.
Read the Docs would also be a hosting option.
@hrmorley34 @rubyFeedback A guy by the name of @logo4poop is working on a custom sphinx theme, so don't worry about style.
Hey! I'm the guy with the name logo4poop. @Semisol will be helping me improve what I have worked on with sphinx. If you wish to also contribute and make it look more modern, I will link the sourcehut repository. https://git.sr.ht/~logo4poop/wikihut
Links in the Welcome dialog will need to be changed as well as Help -> Manual
