[Ardour-Users] Ardour Manual Topics

[Thomas Vecchione]

Howdy Folks-

  Well I have some spare time sitting in my hotel room so I figured I woudl
try to get this out to everyone as a general information, and discussion
starter to hopefully push some things ahead.  Some folks have already been
jumping in and making edits and this is great.  One thing to keep in mind,
is to break everything down into small articles.  Take a look at the MIDI or
Editor Window section of what is currently there to get an idea.  Each
article there is fairly small, but when we render it as part of the manual
document, it comes out in a much stronger flow.

  This is going to have a couple of general statements, as well as some
topics that are intended to be discussed so that we can move forward and
hopefully lessen the amount of work we need to redo in edits.

  Remember that this is going to be a technical reference manual.  So for
right now try to stay away from workflow related articles, and more stick to
articles that define and describe functionality.

  So a handy piece of information, is how to add articles to the book
definition.  Well this seems a lot more difficult than it is.  If you click
on the book definition("Ardour Reference Manual"), you will get a page that
doesn't have to much information on its own, just a couple of download links
for XML.  However just like a regular article, you can edit this int he same
way (Actions>Edit) and in doing so you will get a navigation menu tree,
where you can add new nodes, or move around existing nodes.  Don't forget to
add nodes for any new documents you create for the manual to the tree here
otherwise we will never see it.  In general though there should still be
enough empty articles in tha already existing structure this doesn't need to
be worried about yet, lets work on filling those out first.

  One thing I do ask though, before you add nodes, if you are going to be
expanding a current section, or adding a new section, please plan it out as
a new document on the daisy wiki first.  Do not add this document to the
book definition, but feel free to create a new document and possibly
reference it in a FIXME statement at the top of the section you are working
on, so that anyone that wants to comment on it can, or if someone is going
to help you in that expansion they can reference that article to continue
adding nodes if needed.

  Ok, one comment emailed to me, that I agree with.  That is that we should
probably reference button clicks by BUTTON-1 or BUTTON-2, etc. instead of
left click and right click.  Do others agree/disagree?

  Also start thinking about ways to make things like images or screenshots
appear fairly uniform across the manual.  One thing I would like to do is
set up a 'style' of sorts for articles discussing various buttons in the UI,
where we would have a screenshot of the button as described, set to a
predetermined size to keep it uniform across all articles of the same
nature.  Then we would describe the shortcut key if there is one.  And then
we would have the article itself.   I wanted to see if anyone had comments
on things like this.  To try to give an example with a simple text layout...

Object Tool:
[Image]  [Shortcut Key]

Description:
Blah Blah Blah

  Are there other similar areas people can see for a system like this(A
specific document type once I find out how to create one) or any other
comments on this?

  Ok since i am half asleep I will end there, thanks for the help.

         Seablade
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.ardour.org/pipermail/ardour-users-ardour.org/attachments/20090513/21b0d52c/attachment-0001.htm>