[doc] Changes to reflect new accounts

To support individual Google accounts as well as opentitan.org accounts, some updates have been made removing references to opentitan.org accounts and emphasising use of documents in repos for sharing.
Updates are visible at https://staging.opentitan.org/book/index.html
- useraccounts.md: Removed outdated material on requesting accounts (now a document)
- design.md: Emphasised use of Working Group shared drives
- README.md: Clarified usage of different document types and shared drives
- glossary.md: Independent update with reformatting

Signed-off-by: Jay Alphey <jay.alphey@lowrisc.org>

Author: jayalp

doc/contributing/detailed_contribution_guide/README.md

@@ -23,27 +23,41 @@ We believe in creating a welcoming and respectful community, so we have a few gr
 
 We list these principles as general guidance to make it easier to communicate and participate in the OpenTitan (and lowRISC) community.
 
-## When to file an issue vs. sending an email vs. creating a document?
+## Use of different methods to share information
 
-GitHub issues and shared Google Docs are generally preferable to email, as these can be more easily tracked, cross-referenced, archived and shared, e.g., with people joining later.
+OpenTitan uses a range of methods to share and document information.
+Each has its advantages and disadvantages, and care should be taken to use the appropriate approach for the circumstance.
 
-Emails (e.g. to the [opentitan-dev@opentitan.org](https://groups.google.com/a/opentitan.org/forum/#!forum/opentitan-dev) mailing list) are suitable to raise awareness of discussions and to call for participation.
-Emails between members of a smaller group are also useful for preliminary evaluations before starting a public issue or document.
+### Communicating through email
 
-When it comes to technical discussions, either shared documents on Google Docs or GitHub issues may be used.
-The former are more suitable for initial, broader discussions, for comparing different options and for soliciting comments from a wider audience on a proposal over a longer period of time, whereas the latter are more suitable for cross-referencing in pull requests, and for presenting the final proposal.
-The outcome of such discussions should always be summarized in a GitHub issue for later reference.
+Emails are convenient but they cannot easily be tracked, archived and shared, especially over a period of time.
+OpenTitan has a number of mailing lists and emails to these are encouraged to raise awareness of discussions and to call for participation.
+However, detailed sharing of information should use one of the other options.
 
-## Where do we discuss implementation details/proposals before creating PRs?
+### Using Google Docs
 
-A shared Google Doc is suitable for initial, broader discussions, for comparing different design options and for a wider audience and agile commenting, but not for revisioning, referencing and storage in the repository.
-Therefore, such a shared document should always be linked from a GitHub issue and the outcome of this discussion should be summarized in that issue.
-For short proposals, the entire discussion can be had in a GitHub issue, without a linked document.
+Google Docs are valuable for initial, broader discussions, for comparing different options and for soliciting comments from a wider audience on a proposal over a longer period of time.
 
-## How to/why use Google Docs?
+However, Google Docs in a personal workspace can easily be lost or have limited visibility.
+Google Docs are best used within the context of a committee or Working Group.
+They should then be stored on the associated shared drive, rather than in a user's personal workspace.
 
-Collaborative documents are more useful than GitHub issues for initial, broader discussions, for comparing different design options and for a wider audience commenting on a proposal over a longer period of time, or when interactive editing is required.
-We often make use of a Google Doc to start the discussion of an idea or proposal, before later converting it to Markdown and moving to GitHub (e.g. as a PR adding new documentation).
+A shared Google Doc and any discussion and changes is not visible in the repository.
+Good practice is to create a GitHub issue, link the Google Doc from the issue and summarise the discussion in the issue.
+
+### Using GitHub Issues
+
+GitHub issues give a formal record for smaller items, generally associated with a specific action.
+They are suitable for cross-referencing in pull requests, and for presenting smaller proposals.
+
+They are used in the [RFC process](../../project_governance/rfc_process.md) to track and summarise [individual RFCs](https://github.com/lowRISC/opentitan/issues?q=is%3Aissue%20label%3ARFC%3AApproved%20updated%3A).
+
+They are typically not a good location for extensive specifications or for information which has a longer lifetime.
+
+### Using markdown documents
+
+Markdown documents are the preferred tool for formal documentation which is likely to need to be referred to at a later point.
+These are used for this OpenTitan documentation guide and for documenting processes or specifications.
 
 ## When to assign issues or request specific reviewers?
 
@@ -100,9 +114,11 @@ The lightweight process is:
    If so, follow the [[Security Issues Process](../README.md#security-issues).
 3. [Create a GitHub issue](#working-with-issues) to raise awareness, start the discussion, and build consensus that the issue needs to be addressed.
    For more information, refer to [Communication](#communication).
-4. Start discussing possible solutions in a smaller group, possibly outside of GitHub, but in a shared document (we typically use Google Docs for convenience) that is linked to the original GitHub issue.
+4. Start discussing possible solutions in a smaller group.
+   Typically this would be an OpenTitan Working Group.
    Find consensus inside the interest group and come up with a proposal.
    For short proposals, the entire discussion can be had in a GitHub issue, without a linked document.
+   For longer proposals, use a Google Doc in the Working Group shared workspace and link from the GitHub issue.
    For more information, refer to [Communication](#communication).
 5. Summarize the outcome of the discussion or the proposed solution in the original GitHub issue.
    For bug fixes, proceed to Step 8.
@@ -252,7 +268,7 @@ Some reviewers may be assigned by default depending on the paths of changed file
 To balance the review load, you are welcome to also request a review from other people familiar in the corresponding area.
 However, you should not request a review from more than 2 to 5 team members, as this increases the review load to unsustainable levels.
 
-## Who should review PRs?
+## Who should review PRs?(#code-review)
 
 Contributors should request reviews from:
 * people regularly working on the affected parts of the code, and

doc/contributing/hw/design.md

@@ -23,24 +23,22 @@ The concept of a design might come from a variety of inspirations: a known requi
 Regardless of the inspiration, the concept should be codified into a brief proposal with basic features.
 This is as opposed to minor modification proposals to an existing design, which can be handled as a GitHub pull request or issue filing associated with the existing design.
 This proposal should be in **Google Doc** medium for agile review capability.
-Ideally this proposal document would be created in the Team Drive, but if the author does not have access to the team drive, they can share a privately-created document.
+The author can share a privately-created document but this should be moved to a shared drive for a Working Group for collaboration.
 
 Design proposals should follow the recommended [RFC (Request for Comment)](../../project_governance/rfc_process.md) process, which handles all such proposals.
 If the RFC potentially contains information that could be certification-sensitive (guidance to be shared), send a note to security@opentitan.org first for feedback.
 The OpenTitan Technical Committee may be able to suggest other collaborators to help with early stage review.
 
 An example of a canonical RFC will be provided *here* (TODO).
 
-
 ## Detailed Specification
 
-Once past initial review of the feature set and high level description, as well as potential security review, the full detailed specification should be completed, still in Google Doc form.
+Once past initial review of the feature set and high level description, as well as potential security review, the full detailed specification should be completed, still in Google Doc form within a Working Group.
 The content, form, and format are discussed in the [design methodology](./methodology.md) and [documentation methodology](../style_guides/markdown_usage_style.md) guides.
 The outcome of this process should be a specification that is ready for further detailed review by other project members.
 The content and the status of the proposal can be shared with the team.
 
 An example of a canonical detailed specification is the pinmux specification which can be found in the TeamDrive under TechnicalSpecifications --> deprecated, for those that have access to that resource.
-(Google Docs that have been converted into Markdown on GitHub are archived here).
 
 Note that when developing OpenTitan security IP, designers should follow the [Secure Hardware Design Guidelines](../../security/implementation_guidelines/hardware/README.md).
 
@@ -67,12 +65,10 @@ friendly, [Comportability](./comportability/README.md) equivalent, etc., as indi
 
 A good example of an initial skeleton design can be seen in [Pull Request #166](https://github.com/lowRISC/opentitan/pull/166) for the AES module.
 
-As part of the GitHub filing process, the Google Doc specification must be converted into a Markdown specification.
-(Tip: there are Google Doc add-ons that can convert the specification into Markdown format).
+Once the specification is ready to be published, it should be converted into a Markdown specification and stored in the OpenTitan repository.
 Once this is completed, any specifications on the Team Drive should be moved to the deprecated section of the drive, with a link at the top indicating that the document is for historical purposes only.
 This applies only for those specifications that originated on the Drive.
 
-
 ## Full Design
 
 As the design develops within the OpenTitan repository, it transitions into "D0", "D1", etc., [design stages](../../project_governance/development_stages.md) and will be eventually plugged into the top level.

doc/project_governance/useraccounts.md

@@ -15,14 +15,17 @@
 ### Partner Individuals
 
 Partner Individuals are those working for an OpenTitan Project Partner and designated by that Project Partner as one of its contributors to the OpenTitan project.
-No separate legal agreement beyond the partner agreement is required.
 
-Partners may identify individuals as Partner Individuals by requesting an [OpenTitan account](./useraccounts.md#requesting-a-partner-individual-account).
-A number of OpenTitan accounts are available according to the Partnership agreement.
-By identifying an individual as a Partner Individual, the Partner authorises them to agree to the terms in the OpenTitan CLA when making contributions.
+By identifying an individual as a Partner Individual, the Partner authorises them to agree to the terms in the OpenTitan Contributor License Agreement (CLA) when making contributions.
+See [CONTRIBUTING.md](https://github.com/lowRISC/opentitan/blob/master/CONTRIBUTING.md) for more information on the CLA.
+No separate Corporate Contributor License Agreement beyond the partner agreement is required.
 
 If a Partner Individual leaves the employment of a Project Partner, the Project Partner must notify lowRISC C.I.C. promptly so that they can be removed from the Project.
 
+Partners may identify individuals as Partner Individuals up to the limit specified in their Partnership agreement.
+If you have more people wishing to get involved than the free entitlement from your partner membership, further user accounts can be purchased.
+If an account is not needed, it can be closed by contacting get-involved@opentitan.org and the account entitlement reused.
+
 ### Individual Collaborators
 
 Individual Collaborators are individuals who wish to make a significant contribution to the OpenTitan project, either on their own or as part of a team.
@@ -36,50 +39,6 @@ In most cases where an individual is associated with an organisation, the organi
 If an individual is contributing as an individual collaborator, and is associated with an organisation which is not a Partner, as the individual is assigning licenses to the project,
 the associated organisation will need to sign a [corporate contributor license agreement](./corporate_cla.txt).
 
-## Account Management
-
-### Requesting a partner individual account
-User accounts are available through partner membership.
-Accounts are requested from get-involved@opentitan.org.
-If you have more people wishing to get involved than the free entitlement from your partner membership, further user accounts can be purchased.
-
-The limit on OpenTitan accounts according to your partnership level is applied to **open** accounts.
-If an account is not needed, it can be closed by contacting get-involved@opentitan.org and the account entitlement reused.
-
-### Requesting other accounts
-Individual Collaborators should be proposed by lowRISC or a Project Partner, a decision by the Governing Board and approval by lowRISC after an Individual Collaborator agreement is signed.
-
-### Using an OpenTitan account
-All communications using your OpenTitan account are as part of the OpenTitan community.
-Please be aware of, and comply with, the [code of conduct](./code_of_conduct.md).
-
-OpenTitan accounts are for individuals, and should not be shared between individuals, even within the same Partner organisation.
-
-The OpenTitan account is intended for managing communications within OpenTitan.
-The associated storage ("OpenTitan workspaces") are not intended for long-term storage and there is no guarantee that data will not be deleted.
-- OpenTitan workspaces should not be used as general storage space to store non-OpenTitan material.
-- Company confidential material and non-OpenTitan IP should not be stored in OpenTitan workspaces.
-- lowRISC, as stewards of OpenTitan, are not responsible for management and backup of OpenTitan workspaces.
-- If OpenTitan accounts are closed, associated workspace data is deleted.
-
-### Maintenance of OpenTitan accounts
-If you no longer need your OpenTitan account, please notify get-involved@opentitan.org and the account can be closed.
-
-If a Partner Individual leaves the employment of a Project Partner:
-- the Project Partner must notify lowRISC C.I.C. promptly so that they can be removed from the project
-- a nominated company representative should be specified for account data to be transferred as described in the next section
-
-If an OpenTitan account is not being used, it will eventually be closed, following the process below:
-- OpenTitan account usage will be monitored quarterly
-- Using an account is considered any of the following:
-  - Signing in to the account
-  - Sending a slack message
-  - Any GitHub activity using the account
-- If an account has not been used for **6 months** it is considered **inactive**
-- If an account is **inactive** the owner will be sent a warning that the account may be deleted
-- If there is no response and the account remains **inactive** the account will be **closed** after **one month**
-
-### Management of OpenTitan account data on closure
-When a user account is closed, the account is deleted including all other data stored in the associated personal Google workspace (e.g. Calendar, Gmail, etc).
+## Requesting a user account
 
-If lowRISC C.I.C. is notified of a Partner Individual leaving the Project Partner, user files on MyDrive are transferred to the nominated company representative.
+To request and set up a new user account for a Partner Individual or an Individual Contributor, please contact [get-involved@opentitan](mailto:get-involved@opentitan).