Manual ported to the wiki; new help system

[D. Michael McIntyre]

The initial conversion went OK, so the Rosegarden Manual (formerly the
Handbook) is on the wiki now for good.  This means the help system will
require an internet connection to function, which is a slight problem, but I
think the enhanced maintainability makes it worth it in the long run.

The next phase of work is to fix Rosegarden's help system to replace all the
empty menus and buttons that don't do anything with links to the online help
system.  This is a slog that's heavy on tedium and very light on code, and I
could use a lot of help getting this done if we want it finished before
February.  This is a great project for anybody with a little time to spare,
and an interest in helping out with Rosegarden.

I have a road map document here:

http://rosegardenmusic.com/wiki/doc:roadmap

In this phase, we need to go through the code and find all the
QDialogButtonBox that have a Help button that doesn't do anything, and fix
them.  We should also add any missing Help buttons along the way, unless the
dialog is extremely trivial.

Once the dialog-specific help is pulled out of the main manual
(http://rosegardenmusic.com/wiki/doc:manual-en) we'll move on to the major
editors; for example, pulling the notation-related dialogs together into a
page that will be accessed from the notation view's help menu.  After the
editors are complete, the rest of it should be "main window help" or close
enough, and then we'll turn the main entry page into a table of contents
linking to all the other pages of links to other pages.  Initially, we'll just
recycle old content with minimal editing, and eventually we should fill in all
the gaps, providing pages for all the assorted sundry things for which there
never has been any proper help. In the long run, I want to fold most of the
old Rosegarden Companion into this as well, making it a combination manual and
tutorial.

We can release with the docs in a sorry state (every other project does) so
the most important single thing is getting all the code work done up front.  
It's very easy code work, and again, this is a great opportunity for anybody
who can use a text editor and who understands the simplest things about code
(change "PresetHandlerDialog" to "MidiFilterDialog" and paste this here and
that there, and you're done.  It's very formulaic and straightforward, but not
quite scriptable.)

If there are any takers, we should figure out a way to coordinate and avoid
duplicating effort.
--
D. Michael McIntyre


------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
Rosegarden-devel mailing list
Rosegarden-devel@... - use the link below to unsubscribe
https://lists.sourceforge.net/lists/listinfo/rosegarden-devel

[Heikki Johannes Junes]

2009/10/30 D. Michael McIntyre <michael.mcintyre@...>

The initial conversion went OK, so the Rosegarden Manual (formerly the
Handbook) is on the wiki now for good.  This means the help system will
require an internet connection to function, which is a slight problem, but I
think the enhanced maintainability makes it worth it in the long run.

No objections. Especially, this decision supports the "release early and release often"
ideology, and, the Agile slogan "working software over complete documentation".

What about naming documentation according to the version ? :

  "Rosegarden Manual for version xxx" or
  "Rosegarden Manual, for version xxx" or
  "Rosegarden xxx Manual" or
  ...

Historically the documentation was bound to the released version anyway.

Best wishes,

Heikki

------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
Rosegarden-devel mailing list
Rosegarden-devel@... - use the link below to unsubscribe
https://lists.sourceforge.net/lists/listinfo/rosegarden-devel

[D. Michael McIntyre]

On Friday 30 October 2009, Heikki Johannes Junes wrote:

> What about naming documentation according to the version ? :
> [...]
> Historically the documentation was bound to the released version anyway.

Thorsten Alteholz wrote:

> Did you consider having several versions of the manual on the wiki?
> After the release of Thorn the manual will be up to date. But what will
> happen if new features are implemented in Thorn+1?

You both raise a valid point which I must admit I hadn't even considered.

I've thought about it at length, and I have to come down on the side of
maintaining the online manual perpetually at $CURRENT_VERSION, and leaving
users of old versions hanging out to dry if it comes to that.  Old versions in
the field are a reality, true enough, but supporting old versions is not
mandatory, and it's a headache on many levels.

The last time I tried to file a bug against KDE, they rejected it outright,
because I'm not running the current release.  There's a lot to like about that
approach, and I wish we had a practical way to do the same thing here.  We
have the "newer version available" feature, and Thorn is a different kind of
Rosegarden in that it is very easy to install and run alongside any package
you might have.

Arguments that installing a new version will corrupt the stability of a
cherished 17-year-old installation of Debian Tyranosaurus Rex have no traction
any longer, because you don't even need to *install* the thing, and you can
build it successfully against locally-compiled libraries in /usr/local (when,
eg. the system Qt is at 4.4 and you've built 4.5 to /usr/local; I've done
this, and it works fine).

I'm not suggesting the stock answer to all questions should be "compile your
own from scratch, even if you have to compile a dozen libraries from scratch
too" but I think this possibility existing does make it more acceptable to
leave the manual at $CURRENT_VERSION and forget about trying to maintain a
long chain back to what went before.  Especially if most of the update work is
done just before or immediately after a new feature release.

In practice, too, the manual has always been perpetually out of date and
incomplete anyway.  We ship features first, and write the docs two years
later, as a rule.  All attempts to institute a project culture to the contrary
(you code it, you document it!) have met with only limited success.

So I think that's where I'm coming down myself, but I'm definitely looking at
this as a lazy person wanting to avoid having to do more than the minimum
possible work on maintaining this whole mess, and I'll admit the strategy I'm
coming down in favor of is not what I'd consider the best or most perfect
solution to the whole problem.  The right thing to do would be to maintain a
separate version of the manual per release version, clearly, but in practice,
I just don't think it's worth the extra work.

Besides, users don't actually read this stuff anyway for the most part.
--
D. Michael McIntyre

------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
Rosegarden-devel mailing list
Rosegarden-devel@... - use the link below to unsubscribe
https://lists.sourceforge.net/lists/listinfo/rosegarden-devel

[Emanuel Rumpf-3]

I think having one  version is enough.
Description for older versions should be kept at the bottom of the
sections though,
with a remark as "This text/feature was valid unil 1.7.3 but changed
in version 10.09"

In the current section "Valid since version 10.09, for older versions
see below."

--
E.R.

------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
Rosegarden-devel mailing list
Rosegarden-devel@... - use the link below to unsubscribe
https://lists.sourceforge.net/lists/listinfo/rosegarden-devel

[Jim Cochrane-7]

On Fri, 30 Oct 2009 10:50:30 -0400
"D. Michael McIntyre" <michael.mcintyre@...> wrote:

> On Friday 30 October 2009, Heikki Johannes Junes wrote:
>
> > What about naming documentation according to the version ? :
> > [...]
> > Historically the documentation was bound to the released version
> > anyway.
>
> Thorsten Alteholz wrote:
>
> > Did you consider having several versions of the manual on the wiki?
> > After the release of Thorn the manual will be up to date. But what
> > will happen if new features are implemented in Thorn+1?
>
> You both raise a valid point which I must admit I hadn't even
> considered.
>
> I've thought about it at length, and I have to come down on the side
> of maintaining the online manual perpetually at $CURRENT_VERSION, and
> leaving users of old versions hanging out to dry if it comes to
> that.  Old versions in the field are a reality, true enough, but
> supporting old versions is not mandatory, and it's a headache on many
> levels.

Michael - Would it take much work/time to include a "snapshot" of the
documentation in its current version for a particular release?  This
would allow a user to refer to these docs on his own machine (which
would have been installed when he installed RG) if, e.g., if he finds
that the online docs are so different from his old RG version that he
gets confused.

If including this snapshot does not involve much work, perhaps this is
an adequate solution.  If it involves too much work, then, well,
sorry for the noise.


Jim

>
> The last time I tried to file a bug against KDE, they rejected it
> outright, because I'm not running the current release.  There's a lot
> to like about that approach, and I wish we had a practical way to do
> the same thing here.  We have the "newer version available" feature,
> and Thorn is a different kind of Rosegarden in that it is very easy
> to install and run alongside any package you might have.
>
> Arguments that installing a new version will corrupt the stability of
> a cherished 17-year-old installation of Debian Tyranosaurus Rex have
> no traction any longer, because you don't even need to *install* the
> thing, and you can build it successfully against locally-compiled
> libraries in /usr/local (when, eg. the system Qt is at 4.4 and you've
> built 4.5 to /usr/local; I've done this, and it works fine).
>
> I'm not suggesting the stock answer to all questions should be
> "compile your own from scratch, even if you have to compile a dozen
> libraries from scratch too" but I think this possibility existing
> does make it more acceptable to leave the manual at $CURRENT_VERSION
> and forget about trying to maintain a long chain back to what went
> before.  Especially if most of the update work is done just before or
> immediately after a new feature release.
>
> In practice, too, the manual has always been perpetually out of date
> and incomplete anyway.  We ship features first, and write the docs
> two years later, as a rule.  All attempts to institute a project
> culture to the contrary (you code it, you document it!) have met with
> only limited success.
>
> So I think that's where I'm coming down myself, but I'm definitely
> looking at this as a lazy person wanting to avoid having to do more
> than the minimum possible work on maintaining this whole mess, and
> I'll admit the strategy I'm coming down in favor of is not what I'd
> consider the best or most perfect solution to the whole problem.  The
> right thing to do would be to maintain a separate version of the
> manual per release version, clearly, but in practice, I just don't
> think it's worth the extra work.
>
> Besides, users don't actually read this stuff anyway for the most
> part.

------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
Rosegarden-devel mailing list
Rosegarden-devel@... - use the link below to unsubscribe
https://lists.sourceforge.net/lists/listinfo/rosegarden-devel

[Emanuel Rumpf-3]

2009/10/30 Jim Cochrane <ml3@...>:
>
> Michael - Would it take much work/time to include a "snapshot" of the
> documentation in its current version for a particular release?

That could be achieved through a web-grabber as wget I think.

--
E.R.

------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
Rosegarden-devel mailing list
Rosegarden-devel@... - use the link below to unsubscribe
https://lists.sourceforge.net/lists/listinfo/rosegarden-devel

[D. Michael McIntyre]

On Friday 30 October 2009, Jim Cochrane wrote:

> Michael - Would it take much work/time to include a "snapshot" of the
> documentation in its current version for a particular release?

Well, that's an interesting one.  Taking a snapshot is a bit complicated, but
possible.

The larger problem is the fact that all the hard links in the code are going
to refer to online locations, and it's not trivial to redirect all of them to
point to some directory somewhere instead.  (Not insurmountably difficult
either, but not trivial.)

I think one way or the other, it's probably safe enough to keep moving in this
direction for the moment, and worry about what to do later when later gets
here.
--
D. Michael McIntyre

------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
Rosegarden-devel mailing list
Rosegarden-devel@... - use the link below to unsubscribe
https://lists.sourceforge.net/lists/listinfo/rosegarden-devel