Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation overhaul. #215

Merged
merged 1 commit into from
May 12, 2021
Merged

Documentation overhaul. #215

merged 1 commit into from
May 12, 2021

Conversation

arsing
Copy link
Member

@arsing arsing commented May 10, 2021

This refactors the docs/ directory into docs/ and docs-dev/ for
user documentation and developer documentation,
with the following overall motivations:

  • Remove developer documentation from HTML documentation so that users do not
    land on it. Ideally this would be something like docs/user/ and docs/dev/
    but GitHub does not allow using anything except docs/ for the root.

  • Change PKCS#11 library documentation to focus exclusively on the case of
    users installing it in production. This means replacing mentions of
    "the user you will run aziot-keyd as" with "aziotks", etc.

  • Don't link to HTTP API docs from the index since they're only useful
    for host module authors. They're linked from the host-module doc instead.

    Also, the TPM service is exclusively an internal service, so move it to
    developer docs.

  • Move packaging.md to developer docs since the user does not need
    the level of detail it provides about what the package contains.
    The user docs only cover the super-config and a new page about
    the aziotctl binary.

  • Hard-code the nav bar instead of letting Jekyll generate it, so that
    it preserves the order of pages rather than sort them alphabetically.

This refactors the `docs/` directory into `docs/` and `docs-dev` for
user documentation and developer documentation,
with the following overall motivations:

- Remove developer documentation from HTML documentation so that users do not
  land on it. Ideally this would be something like `docs/user/` and `docs/dev/`
  but GitHub does not allow using anything except `docs/` for the root.

- Change PKCS#11 library documentation to focus exclusively on the case of
  users installing it in production. This means replacing mentions of
  "the user you will run aziot-keyd as" with "aziotks", etc.

- Don't link to HTTP API docs from the index since they're only useful
  for host module authors. They're linked from the host-module doc instead.

  Also, the TPM service is exclusively an internal service, so move it to
  developer docs.

- Move packaging.md to developer docs since the user does not need
  the level of detail it provides about what the package contains.
  The user docs only cover the super-config and a new page about
  the `aziotctl` binary.

- Hard-code the nav bar instead of letting Jekyll generate it, so that
  it preserves the order of pages rather than sort them alphabetically.
@arsing
Copy link
Member Author

arsing commented May 10, 2021

@kodiakhq kodiakhq bot merged commit 81b066b into Azure:main May 12, 2021
@arsing arsing deleted the docs branch May 12, 2021 23:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants