search

openziti / ziti

The parent project for OpenZiti. Here you will find the executables for a fully zero trust, application embedded, programmable network @OpenZiti
https://openziti.io
Apache License 2.0
2.87k stars 160 forks source link

built-in documentation for Linux package #1240

Open qrkourier opened 1 year ago

qrkourier commented 1 year ago

Install a user manual (man) for each Linux package after they're available in https://github.com/openziti/ziti/issues/911

qrkourier commented 1 year ago

Needed:

qrkourier commented 10 months ago

Have you already discussed this, @plorenz, @ekoby, or @scareything? I've read plenty of man pages but have yet to write any. :slightly_smiling_face:

The man page for the ziti CLI is an opportunity to be extremely helpful and valuable to the server administrator with built-in, authoritative documentation.

As for tooling, I like the idea of maintaining Markdown manuals in the main Ziti repo that are automatically translated to man pages for each Linux package. This will be nicer for the maintainers because only one set of authoritative docs is needed, and it's probably a simple matter to convert the formats and lint the output in CI. I'll happily help with that last part and maintain the documentation sources.

Ideally, we'll use the same tools and approach for this user manual and the one for zrok.

plorenz commented 10 months ago

The markdown -> man approach seems nice