Process for adding to documentation....

[gooseleggs]

Not an issue, but what is the state of documentation. I gather DocFX is now dead. What is/are the main Ziti sites now? How can I help with doco (if at all). Maybe have a “how to add to our documentation” page. I still like the “Big Book of Ziti” idea which is a full manual.

[qrkourier]

Correct, we switched https://openziti.github.io/ from DocFX to Docusaurus for static page generation. This is the main Ziti site. There's also the blog site.

Now the Markdown source is all under the "docusaurus" folder in https://github.com/openziti/ziti-doc/tree/main/docusaurus. The main README for this repo attempts to give you what you need to contribute to docs. If it falls short, then our first improvement should be there!

Generally speaking, docs input is warmly welcomed. Remember to use GitHub verified commits. This is typically accomplished by GPG signing commits with git. Edits made in the web browser are verified too. If you're considering a major change it's best to start a conversation first by opening a GH issue in this repo detailing the goal you have in mind, or problem you'd like to solve.

[gooseleggs]

Thanks. As a comment, which may need to be pulled out to a separate issue, but it relates to the README. I think the README needs to have some definition about destination of documents.

So...

There are a number of sections that are split out - that being Docs APIs Guides Glossary Ops

What determines if some documentation belongs in the Doc section, or if it is an Ops section document? I wonder if the Ops section should just fall under Docs?

Consolidation There is also technical documentation split out across the documentation. For example, if I want to understand about controller configuration, there are currently two places to find information:

• https://openziti.github.io/operations/configuration/controller
• https://openziti.github.io/operations/controller.

Should we consolidate all controller documentation in the one place under the heading of Controller? This would be the same for other components.

Say I want to find out about Posture Checks. I want to implement it for instance. I would think that this documentation would exist as an Ops type documentation. To find it, I need to perform a search, and then find it under Core Concepts > Security > Authorization > Posture Checks. Totally not where I would expect. What I would expect is most of that page content would be under Ops. The Core concept would explain what it is, what it can do, but the actual implementation is under Ops.

Also, wanting some definition around what is a Guide and what is a Blog. Reason for this, looking at the blog site, there are articles such as this: https://blog.openziti.io/setting-up-oracle-cloud-to-host-openziti. Most of this article is actually a guide on how to do it. So, should this be moved to the guide section?

[dovholuknf]

This is such a difficult area and everyone ends up having an opinion. Sometimes there's total agreement, lately there's been a lot of disagreement over this particular topic. It seems like the Ops section is destined to be removed. We have a weekly meeting around doc on monday. I'll bring this up then. I expect there will be changes made to this organization very soon, if not next week. It's also an ever-green area for improvements, so your feedback is useful.

In general, many of the ideas presented in this video resonate with me https://www.youtube.com/watch?v=t4vKPhjcMZg. It's worth a watch. I think most people who review that video come away with the same general idea.

Here's my general thoughts on the matter. I have "learning" sketched out locally but haven't pushed it yet.

• Guides/How-Tos - these don't explain. they get right to the point and tell: "do this, do that, look you did it"
• Blogs - hey we did this, it was neat, check it out, here's the bumps, here's how I did it, here's why. Longer form content.
• Reference Doc - details. lots of details. often very technical with lower amount of explanation
• Learning/Tutorials - explain in depth. what each step does, what it is, what it represents. much longer content, gets you to the same place as a guide/how-to but explains much more

[gooseleggs]

FOLLOWING IS JUST THOUGHTS...

So I found myself thinking about this, for reasons unknown. I looked at the video. I think this concept is fine if what you are developing is developer focused. Which then got me to thinking. OpenZiti is a project of two halves.

The first half is developer focused: SDKs. Maybe documentation layout as per the video is fine for the developers. Guides would be like the 'hello world' example. Reference Doc would be Doxygen output (Classes / Methods etc), Howto is about doing different aspects, ie MFA (no idea just spit-balling)...

The second half is end user focused: Ziti Overlay. This may (probably) be a different documentation style from the developer documentation.

An example of the difference would be: Reference documentation

Developer: Class constructors/destructors/methods/properties documentation - pulled from source code (yah for Doxygen) End User: Topic (ie MFA) with description and configuration example.

I read a lot of CakePHP documentation and they have a theme that runs through all the documentation. They start with the My first application tutorial which is a web based Book catalogue. Then, all through the document, any examples are referenced to that tutorial. For instance, when you look up how to do database finds using the framework, the examples given are finding book, authors or combination of both - just food for thought.

So, just thought that different documentation styles might be an idea.?

In regards to your types...

"Blogs - hey we did this, it was neat, check it out, here's the bumps, here's how I did it, here's why. Longer form content." - the concern I have is with the here's how I did it as this is a guides document. I wonder if it would be "Blogs - hey we did this, it was neat, check it out, here's the bumps, here's why, here's a link to the guide. Longer form content.".

[qrkourier]

To your point @gooseleggs, my hope is this reorganization serves both types of reader: developer and operator, by structuring the documentation around the progressive learning experience: introduction, then reference, then guides.

What do you think about the new outline, at least the rough high-level organization and nav? I'm actively incorporating some additional feedback that will further refine the presentation and navigability.