FLOSS manual corrections and suggestions

I’m taking Seablade’s advice and reading through the Ardour manual carefully.
Normally I avoid manuals as much as anyone else, but I was pleasantly surprised,
to find the manual quite readable and friendly on the face of it.

In the interests of improving something good,
and in leu of not trusting the posting/commenting options, which seem to hang and crash,
I thought it would be best to post corrections and improvements here,
where people can find them and also easily contribute insights for others.

The first page I read carefully was

STARTING JACK ON UBUNTU, since I’m running Ubuntu 11 (tried Ubuntu 10 without success):

Here are my thoughts on that page:

Starting Jack on Ubuntu Page:

(1) Jack / Ardour only seem to run properly in Ubuntu 11.10 with popular soundcards like m-audio.
This version of Ubuntu no longer has dropdown menus.
The screens shown are disorienting, since they don’t match what people actually see, nor serve instructional purposes.

(2) On the Jack Main box, “Status” seems to have been replaced with “Session”, and does not open up to a dialog pictured above. No real knowledge of either option seems to be conveyed. If the purpose is to acquire familiarity, it fails since there is no match.

(3) Perhaps two separate pages would work, one for Ubuntu <=10, and one for Ubuntu 11.

(4) “Currently, JACK can only communicate with one hardware audio device at a time.” This is a really important fact, if still current, and should be bold/red so it isn’t missed. I wasted hours trying to get input from one card and output onboard working.

(5) A quick explanation of sample rate options and why you would pick them, with possible drawbacks would be helpful.

(6) “The maximum number of channels is limited by the number of output and input channels supported by your physical audio device.” Another important fact, which should be highlighted in blue or something to save users hours of futile struggles.

(7) “With the JACK server on, …” It might be better underlined, and expressed more clearly: “TURN THE JACK SERVER ON, by pressing ‘Start’ button, …”, and followed by “Start the ARDOUR program now:…”

(8) Explaining that Ardour automatically connects itself a certain way, with a screenshot of Patchage would be useful.

(9) Some explanation of the Patchage program would be good here, and why/how one would use each of JACK, Patchage, Ardour for setups, or in what order, and who overrides who, or how/why changes to patching could be ignored, rerouted against the user’s wishes, or stored so that one isn’t re-inventing the wheel every startup. i.e., provide an example first-time setup procedure, and subsequent startup procedure for a simple, fresh recording session.

(10) Generally, numbering the sections, making the headings standout clearer from text so that bold and underlining could be used, and providing a useful local hyperlink navigating system on every page that is longer than a typical screen. Then the user could jump back and forth between sections and screenshots, to recap or pick up pointers. Allowing resizing of page width would help to allow displaying help-pages while working with the programs.

(11) Find out why comments are not working properly, or display them and let users know that they were actually sent!..provide a backbutton to return to the current page after posting a comment.

As a way of adding such features without the work, one might post the FLOSS manual on Blogger, and phase out the old posting.

Nazaroo

STARTING ARDOUR ON UBUNTU page:
there’s a few potential glitches that Ubuntu users are likely to run into.

A good rule of thumb for complex software interactions here is,

       "If something can go wrong, it will."

Some of this has to do with installation, but it is critically important to mention it:

(1) In Ubuntu, all users, including ‘root’ have to be enrolled in the “Audio” group.
This can be done from the command line in a terminal window.

(2) The Ardour program (and the user) has to have read/write access to storage areas (drives etc.) in order to make folders, and store project files.

(3) Some sensible but basic discussion about how to organize your recording projects, diskspace needed, how to load and save and start new projects,

(4) Some mention of how Ardour will fail and hang here at the opening dialog is in order here, with pointers to possible causes of the snag, like write-permissions to directories etc.

(5) Some recap and explanation of the general order of launching programs for recording should be discussed, before all kinds of programs have been launched by the user in various orders, causing problems likely to be vague and difficult to hunt down and correct.

(6) A basic launch script should be designed, posted and explained, to allow easy startup and shutdown of a current project.

(7) This page as found was of little use for finding out what to do when a problem is encountered: Some kind of simple table of symptoms and likely causes should be built up or linked to.

Nazaroo

@nazaroo2: the FLOSS manual is not produced, managed, hosted or edited by the core developers of Ardour. Any issues with the manual need to be reported to the FLOSS manual team at FLOSS manuals. In addition, anyone can become an editor and you will likely find that they will suggest that you make the changes yourself.

Making such comments here on the ardour forums is almost (though not quite) like tipping them into a black hole.

Thanks Paul.

I would have thought more people (Ardour users) would frequent this forum (or one like it) than would be reading online manuals.

Oh well, I could try both avenues,
but I can’t believe posting useful info here would be a nuisance,
or literally a black hole. :slight_smile:

Does Ardour make its own manual,
or put another way, do the Ardour people recomment the FLOSS manual over their own if there is one?
I’m a bit confused as to where the primary sources for documentation and ongoing use of Ardour is to be found.

peace
Nazaroo

Oh well, I could try both avenues, but I can't believe posting useful info here would be a nuisance, or literally a black hole. :)

It isn’t a nuisance, and I think you misunderstood what he meant by black hole. He meant it would probably never get integrated into the FLOSS Manual by posting in here as there is no guarantee anyone that maintains that manual still is posting in here. Not because we don’t want it to, but because many people here have nothing to do with the FLOSS Manual’s creation and maintenance at this time. Ardour’s support gets spread out between here, mailing lists, and IRC, and while there is some overlap between them all, there isn’t complete overlap either. So you get different people in each venue.

Does Ardour make its own manual, or put another way, do the Ardour people recomment the FLOSS manual over their own if there is one?

The tech ref I linked to briefly in that other post I believe you are referring to is the closest thing these days, but incomplete as well and since A3 is nearing I am not putting any more time into it. It also is not really an ‘official’ ardour manual, both the FLOSS manual and the tech ref were made by people in the community in their spare time of course, much like how Ardour is made(Paul being the only regularly paid person working on Ardour). The FLOSS Manual is the best source of information for anyone new to Ardour, the TechRef covers certain aspects more in depth from the standpoint of a technical reference, and there are a variety of videos and blog postings about features in Ardour people can google, but that makes up the bulk of ‘documentation’ at this time sadly.

       Seablade

@nazaroo2: we have made several efforts at creating a reference manual. Seablade pointed you towards its current incarnation, which is also on the Support page. Alas, it is far easier to attract developers to a project like Ardour than writers. People show up, promise to write some docs, and it comes to nothing. We’ve tried a variety of authoring systems, wikis etc. Nothing really gets around the fact that writing docs for a program as large and as complex as Ardour is a huge task and fundamentally requires a lot of time and effort. It doesn’t help that Ardour3 is substantively diferent in many important areas from Ardour2.

The FLOSS manual was a welcome contribution to the “documentation scene” and is by far the best thing for new users to start with. I would suprised if any of the people involved in its creation read the forums here with any frequency. But you never know …

Thanks for all of your responses: I’ve probably still got that born-again glow of a newbie, and have much to learn from the kung fu masters of Ardour.