30. August 2022

[dimakuv]

Agenda

(please write your proposed agenda items in comments under this discussion)

• Gramine documentation and web page

Gramine documentation

Mona: people find it difficult to work with Gramine, partly because of the documentation. Many customers turn their attention to Gramine who don't know how Intel SGX works. Thus, we keep answering the same questions. There are many customers asking different people at Intel, so these people need some training on Gramine, and the customers need easy-to-read documentation.

Benny has a restructuring proposal on Gramine documentation:

• Problem: the information is in our readthedocs. A person starts with the main page, that immediately has a link to GSC -- but the person doesn't know what GSC is at this point. Or if a person goes to QuickStart, then he will learn a lot of random stuff -- how to install Gramine and run examples, i.e., the person will learn the most complicated way of using Gramine.

• Proposal: start with "4 alternatives of using Gramine":

  1. Core Gramine -- install Gramine, write a manifest, run it.
  2. Gramine Docker image -- our base Gramine Docker image with Gramine installed, you use the Docker container, write the manifest, rest same as 1.
  3. GSC -- gsc build, gsc sign (on top of core Gramine).
  4. Curated apps -- interactive script (on top of GSC), set of pre-configured applications.

• We should restructure the docs per above structure with 4 alternatives. Very brief introduction of Gramine, then "there are 4 ways of using Gramine: pros, cons ..." and links to relevant pages.

• Why this restructuring? Story: A partner wanted to use Gramine, and he already had a Docker image. So GSC would be perfect. But the partner tried first with core Gramine, and only after days learned about GSC. This was a frustrating experience.

Mona: another story. A person heard about Gramine and CCZoo and GSC, but he was not that aware about Intel SGX and the relationships among these projects. So he had an impression that Gramine is purely container-based. It seems important to say that "core Gramine is a building block; for most customers, you should use a more friendly tool on top of Gramine".

Don: let's not damage our documentation by removing the old text. We should keep it, but may move it after the one that is for people who know less about Gramine/SGX (like data scientists). So, Don's proposal is to have two parts for documentation: one for end users and one for developers.

Dmitrii: dislikes the CSS (web design) of our readthedocs. Bullet lists are badly formatted, NOTEs and WARNINGs are annoying, font is too small, line wrapping is too short.

Benny will build this proposal and present it later.

Gramine web page

Benny: gramineproject.io is the first hit in Google search. But it's a bit outdated, doesn't have important information (like GSC), has other problems.

• Mona: hosted by Woju on one of the ITL servers. A revamp/redesign of this web site would be welcome. The CCC proposed their help but they insisted on using Wordpress, which the Gramine team doesn't like (we don't want a complex dynamic PHP engine).
• Borys: we want just a static page (with all the nice JS and CSS scripts/designs, but nothing needs to be dynamically generated on the backend side).

Scott: imagine a data scientist. They don't want to look through two web sites: gramineproject.io and readthedocs. They don't want to read through the scientific papers first, then read some random pieces of developer documentation.

Vijay: we should put our releases on the web page. Just like https://projectacrn.org/ does. In general, the ACRN web site looks good. It is maintained by Intel, there is a tech writer who does it. The ACRN documentation also uses ReadTheDocs engine. Also, there is a nice button "Releases" at the top (Gramine's readthedocs has it at the bottom).

• Everyone seems to agree that both the https://projectacrn.org/ website and their ReadTheDocs can be used for Gramine almost as-is. Problem: the ACRN web page seems to use Wordpress, which Michal opposes.