Re: PROPOSAL: UISG Menu Line Standardization - actually, documentation by now

[James Smith <j-smith physics tamu edu>]

Josh Steiner wrote:
> 
> I hear this argument all the time: "coders don't want to be _forced_ to
> documentation, they just want to code, code, code!".  I understand that
> this is based in reality, but this should not stop us from aiming high
> in our guidlines.  Afterall, isn't the point of the GC to _ensure_ that
> "Gnome Compliant" apps are the shining examples of good free software?
> I might agree that maybe having a program without docs would still allow
> you too qualify for the loosest (is this GC1 or GC5? I am confused here)
> compliance rating.  Many coders out there will not like to put time and
> energy into a well desinged gui, because they think their time could be
> better spent optimising their methods, but this does not mean that we
> should not mandate good gui design in this document.  The very _point_
> of this document is to try to raise the standard of the software out
> there.  To sum up, perhaps the lowest level of compliance does not
> _require_, but strongly encourages docs.  But if you want to earn the
> pride and joy of a high Gnome compliance rating, you best take a little
> time to learn docbook :)  Sound reasonable?

Sounds reasonable to me.  IMHO one of the best things a coder can do is
sit down and figure out what he wants the program to do - before
figuring out how to code it.  This would be a good start of the
documentation - write down everything you want the program to do from a
user's perspective - including how the user would go about doing
things.  Then start coding.  If not in that order, then at least have
the documentation a little ahead of the program code - then it serves a
dual purpose - design spec and rough draft of the documentation.  Also,
include the rough draft with the program so others can see what the
programmer at least had in mind.

--Jim