Beta test feedback - JA (1)

[Dave Offiler]

Email from Josep Aparicio (Beta tester under VS contract) on Tue, 23 Sep 2008 14:56:22

Huw, Dave,

Although I am working on the internals of the code (mostly the
forward operator), I have several things that I can suggest you
now, and which would be easy for you to implement along the
next few days. Essentially, the idea is that the presentation is
confusing for an external user, and risks making it too puzzling
to put it to use. I suggest you below how I would restructure
it to make it look simpler.

-1) Restructure and simplify the deliverable:
     For an external user, the structure of ROPP can be difficult to
     understand while browsing at the page, shortly after having
     gained access. It is thus preferable not to expose the users to
     the internals until later.
     Unless there is some reason that I am missing (copyright or
     similar), I would reduce the deliverable to one single file.
     The confused user will anyway download all files, then look
     inside, and still have some feeling that something may be
     missing. It is simpler to just have 1 file.
-2) Deliverable file:
     Ideally the file's name should be ropp-n.m.tar.gz
     and develop to a subdirectory
     ropp-n.m
     The current "metafile" unpacks within the current directory
     (this is considered inappropriate).
     The modules can then be subdirectories, unpacked and
     uncompressed.
     It is ok to directly unpack all modules, even if the user ends
     up using only a fraction. Something like:
     ropp-n.m/README
     ropp-n.m/COPYRIGHT
     ropp-n.m/INSTALL
     ropp-n.m/grass_ropp_licence.pdf
     ropp-n.m/ropp_tools/
     ...   
     ropp-n.m/ropp_1dvar/
     Again, the user is initially confused, so it is preferable at this
     stage to help the user to feel that everything is simple.
     It is ok to have a README file outside, but it is better to
     just say something like "download the tarball, unpack it, go to
     the main directory and read the INSTALL file".
-3) By the way, the current README is for version 1.2.
     If the above steps are taken, the external README is much
     simpler. An internal README or INSTALL file, prominent
     upon unpacking will suffice.
-4) If you restructure things as above, upgrading may also be
     easier for you, as only the upper tarball and directory have
     the version number.
   
     Josep
    

-- 
Dr. Josep Maria APARICIO
Data Assimilation and Satellite Meteorology Division
Meteorological Service of Canada
2121 Transcanada Hwy
H9P 1J3 Dorval, QC, Canada

Tel: 1-(514)-421-4687
Fax: 1-(514)-421-2106
Josep.Aparicio@ec.gc.ca

[(none)]

Milestone 2.0 deleted

[Dave Offiler]

...and my reply Wed, 24 Sep 2008 09:25:28 :

Josep,

> Huw, Dave,
> 
> Although I am working on the internals of the code (mostly the
> forward operator), I have several things that I can suggest you
> now, and which would be easy for you to implement along the
> next few days. Essentially, the idea is that the presentation is
> confusing for an external user, and risks making it too puzzling
> to put it to use. I suggest you below how I would restructure
> it to make it look simpler.
> 
> -1) Restructure and simplify the deliverable:
>      For an external user, the structure of ROPP can be difficult to
>      understand while browsing at the page, shortly after having
>      gained access. 

We used to have a nice diagram (from the User Guide) showing the
component parts of ROPP, together with a brief description of the
modules on the Overview webpage, but this seems to have got lost when we
ported the download pages to DMI. We recommend users read the open
documentation first (in particular the ROPP Overview guide), but we
could certainly give more information on the high-level ROPP structure
here, before one links to the Downloads page.

Did you read the Release Notes (html) at the top level on the Downloads
page before downloading the ROPP files? If not, did you miss it - so we
need to bring attention to it - or if you read it, it was clearly
inadequate as a structure overview, and we need to better explain it
here. (EUMETSAT consider a RN to be the prime user guide to downloading
and installing any deliverable software - for all SAFs - as it is the
initial user experience, so your feedback on this guide would be most
helpful.)

> It is thus preferable not to expose the users to
>      the internals until later.
>      Unless there is some reason that I am missing (copyright or
>      similar), I would reduce the deliverable to one single file.
>      The confused user will anyway download all files, then look
>      inside, and still have some feeling that something may be
>      missing. It is simpler to just have 1 file.

We do have a single file now - ropp_all.tar - which contains all of the
release files (but modules are still as individual tarballs). This is
documented in the Release Notes (html). But we could present this meta-
file more prominently (first), with the individual tarfiles as
(following) options.

> -2) Deliverable file:
>      Ideally the file's name should be ropp-n.m.tar.gz
>      and develop to a subdirectory
>      ropp-n.m
>      The current "metafile" unpacks within the current directory
>      (this is considered inappropriate).
>      The modules can then be subdirectories, unpacked and
>      uncompressed.
>      It is ok to directly unpack all modules, even if the user ends
>      up using only a fraction. Something like:
>      ropp-n.m/README
>      ropp-n.m/COPYRIGHT
>      ropp-n.m/INSTALL
>      ropp-n.m/grass_ropp_licence.pdf
>      ropp-n.m/ropp_tools/
>      ...   
>      ropp-n.m/ropp_1dvar/
>      Again, the user is initially confused, so it is preferable at this
>      stage to help the user to feel that everything is simple.
>      It is ok to have a README file outside, but it is better to
>      just say something like "download the tarball, unpack it, go to
>      the main directory and read the INSTALL file".

Actually, it would be far from trivial to re-organise the meta-file this
way, as the whole ROPP build system (including the Makefiles which
generate the tarballs) are geared around the separate modules. This is
because not all users want all the modules (e.g. GFZ only want ropp_io -
and ropp_tools - to support BUFR encoding). Others might only want the
ropp_fm to but into a 4-DVar scheme etc... So they have the choice - we
considered they might be more confused having modules they don't want. 

But what we can do relatively easily is to build the meta-tarfile (a)
with the version ID [ropp_all-n.m.tar or just ropp-n.m.tar], and (b)
extract to directly to ropp-n.m. At the moment, the Release Notes advise
manually creating the directory, downloading the meta-tarfile here and
extracting to that directory; this can be automated somewhat.
 
> -3) By the way, the current README is for version 1.2.
>      If the above steps are taken, the external README is much
>      simpler. An internal README or INSTALL file, prominent
>      upon unpacking will suffice.

All of the READMEs are updated for V2.0 now, but this wasn't done in
time for your beta version. But the information in the README is backup;
the main user help on installation is in the Release Notes.

> -4) If you restructure things as above, upgrading may also be
>      easier for you, as only the upper tarball and directory have
>      the version number.

We'll consider this, but we also have to take into account that not all
users want the whole package. Also, individual modules can be changed
more easily, and users only have to download that one if they previously
downloaded it, and not the whole package. Packaging the whole of ROPP
openly in one file (i.e. not as individual tarballs on one archive)
would, I think, take quite some changes to the packaging system (which
Chris Marquardt set up when he was working here), so this could probably
not be done for v2.0; perhaps a future release when we've reviewed how
it might be achieved. We have a policy of continuously simplifying the
internals of the package (reducing 3rd party dependencies, removal of
bundled libraries which are little called etc), so simplifying the
package presentation is an ongoing objective too.

As a compromise for packaging V2.0, we could:
a) rename the meta ropp_all.tar file as ropp-2.0.tar;
b) have this as the first in the list of linked files with the
individual tarballs following as options;
c) arrange for the meta tarfile to automatically extract to a directory
ropp-2.0 (but would still contain the individual module tarballs);
d) document the above in the Release Notes (and overall package README)
with the default being that the meta tarfile is presented as the primary
download file, with individual files as options.

Would this be acceptable for v2.0?


Thanks for the suggestion; we'll put your original email and this reply
in the ROPP Trac system. If you have any others as you go along, please
feed them to us rather than wait until you send in your test report. The
plan was to send us an interim report at week 5 after starting - that
would be the week after next?)

Dave

Note: Action required as above (items a-d on packaging and enhancement of user-interface webpage on GARF) for release version of v2.0, then consideration of suggested package architecture for v3.0.