Documentation section for "Enterprise"?

[NezSez]

While taking notes on setting things up I've noticed that many of our docs are geared for small installations as opposed to actual enterprise usage where LDAP, Kerberos (and AD integration), Actual use of Certificate Authorities, Certs/Key management (ssh, 509, PKI, etc), AFS(Andrew not Apple)/Ceph/ZFS/SAN/NAS/FC/iSCSI, dbase sharding, etc etc are not addressed at all. Should we create a section specific to such enterprise configurations?

As a real-world example, setting up KVM to do live migrations between hosts is a bit more complex and requires things which are not needed at all for a standalone setup on one desktop home server like NFS and SR-IOV of intel 40GB NICs. A college admin setting up a system for students to run containers or VMs on during a class is very different than one person setting this up for home/hobby usage (multi-user security, encrypted memory space/shared mem, etc). iDRAC, IPMI/LOM, OpenManage, and HA/HPC clusters would be other examples.

Putting some of these topics in with the list as we have it now would likely just confuse many users who aren't concerned with such setups, may never have heard of most of these topics, and make for confusing or annoying navigation for someone who just wants things to work without understanding all the details.

I have no agenda, just trying to be considerate. It may not be worth the effort of splitting such topics out at this stage; perhaps once we get more docs, but preventative front-loading can save much hassle later.

[EzequielBruni]

Well for my part, of course, I have no actual experience with enterprise software of any kind. Still, I don't really see why we couldn't have documents for everything all in one place, more or less. People will largely just skim for whatever they;re looking for.

On the other hand, from an organization standpoint, separating the two might make things a little easier for authors and some users.

[sspencerwire]

I'm in the "Let's do everything in the same set of documentation" camp. To me, even a non-enterprise user might be really interested in some of these concepts. I think that leaving the documentation in one place offers an opportunity to educate, and that is never a bad thing. I mean, I'm done with my work life, but I'm still very interested in tech and have learned (since joining the Rocky team) a great deal. That's extremely valuable to me, and I think others will find it so as well.

That's my opinion. I'd love to hear what @wsoyinka and @alemorvan have to say about this suggestion though. I realize that splitting the two sets of documentation out does not keep others from reading and gaining knowledge from it, but I'm not sure that I (personally that is) see the value of splitting it out. Thank you @NezSez!

Another thought, @NezSez is to structure the more advanced topics into the "Books" section. (chapters, etc.)

[alemorvan]

We have already had this discussion with @sspencerwire and @ambaradan (which proves that there is food for thought). Indeed, there are different writing styles among our editors. A good example is our friend @EzequielBruni, who writes great, lively and very enjoyable documents, in a slightly more "blog" format, while mine are more factual and psychorigid, as they are indeed more "enterprise centric". I'm not in favor of dividing our documentation in two either, but why not make a kind of "blog" for those who would feel like writing this kind of documentation. The writing of more corporate material also requires more know-how. For the moment we are not enougth to do this but that what I am looking for.

[NezSez]

To be clear, I wasn't suggesting that we have a whole new site, or "split" anything at all. I don't see how having an additional "section" called "Enterprise Settings" is in any way different from the dozens of existing "Editors" or "Books" or, more to the point given a current discussion in the "Security" channel in MatterMost/IRC, "Security"...which has different concerns in an enterprise or multi-user setting.

Creating something in or like the existing anchors/headings is exactly what I was thinking, just specific to Enterprise rather than casual users with one or a handful of machines. Specifically I have University/GOV/biz admins in mind as consumers of the content that must deal with non-trivial issues of which I can give many examples (ex: how do you get 1000 users to apply security patches to their vm/ve instances on your live migrating cluster farm? I'm not talking about psych/motivation here, I mean the technicals...systemd-timers, notifications, setup local repos for users to access, etc)

FTR: I think there should be a list of SMEs that the Documentation team could ping to get technical reviews before publishing.

[sspencerwire]

Taking a little time to reorg the docs so that an Enterprise section is available (top menu perhaps), isn't a non-starter. @NezSez, I think that you hit the nail on the head in your first start of this thread by us not having enough of that specific content to do this now. It isn't a bad idea to think about how that would look and start planning for that. With regard to the current documentation: The goal is always to encourage writers to use their own style and not to discourage them from writing. Contributions should have the voice of the author. Having a single voice or style to all of the documentation will make them less interesting and worse, will discourage those who wish to write from actually writing. The goal is to obviously have accurate documentation. We don't want docs that are incorrect.

Regarding the content that already is Enterprise ready: The Ansible book and the LXD Server documents come to mind. I know that the LXD Server document is Enterprise ready because it pretty much documents exactly how we used it in the Enterprise when I was still working. I know that the Ansible book is Enterprise ready as well because that is something that @alemorvan uses day-to-day in the enterprise. There may be more examples, but those are two off the top of my head.

[alemorvan]

Maybe we could have a look at tags on mkdocs https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/

[sspencerwire]

Maybe we could have a look at tags on mkdocs https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/

Honestly, this wouldn't be a bad idea. It would certainly make it easy to tag a document as Enterprise, etc., without having a section specific to it. The qualifier would be that the editor would have to recognize the document as enterprise-ready and tag it as part of the editing process. There would be no setup except including the configuration items because we already use Material for MkDocs and this is a built-in feature.

A document writer could propose their document as enterprise-ready when submitted as well.

[NezSez]

I also am in the "same set of documentation" camp. I also wasn't thinking at all of blogs or author writing styles or anything like that, just content from the users perspective and how they can find the info they need/want. "Tags" is an excellent idea, and not something I had thought of which begs explanation since I use them in many contexts all the time!

There are some things I think of as "enterprise relevant" concerns rather than "enterprise ready" per se. Applying security patches, which must also be applied to individual VMs/VEs on a given host where one instance can compromise the entire host with all of it's services/guests.

[sspencerwire]

I also am in the "same set of documentation" camp. I also wasn't thinking at all of blogs or author writing styles or anything like that, just content from the users perspective and how they can find the info they need/want. "Tags" is an excellent idea, and not something I had thought of which begs explanation since I use them in many contexts all the time!

Let's see about pursuing this. I can definitely test the whole thing internally on my lab and then, if it works as we hope, simply push through the changes. It will require a modification to the mkdocs.yml file, so will involve ~web. Great idea, @alemorvan !!

[sspencerwire]

Let's leave this issue open and I'll post back what I find. Probably will not get started on this until tomorrow or later.

[NezSez]

It might be worth looking into the "Was this page useful/helpful" feedback as well. I'm not sure how this feedback could be used to improve the site other than adjusting search results, and possibly helping authors adjust their styles or formats, and it might not be worth the Big O costs on infra/server loads etc. Just a thought.

[sspencerwire]

Just a quick update on this. While we do use Material for Mkdocs, we are currently using a fork of the repository that Neil Hanlon maintains. (infrastructure team). Apparently, the "tags" plugin was not available when he forked and the fork is a bit behind the original repository. I've got a message sent to Neil, but it's mid-week and people have work constraints, so just know that I'm working on this. Thanks!

[NezSez]

I don't think there is any need to rush this...going to be a while before we have many docs that would use this tag, and it will be easy to retro tag any that do.

[sspencerwire]

Thanks @NezSez , but the tagging can be helpful for other things as well. For instance, if you were searching for all of the apache docs or all of the LXD docs, etc. Having tags available would be an added benefit. Also, I'm retired and I've got time. ;-)

To test, I've uninstalled the Material for Mkdocs (locally) from Neil and re-installed the official package. At least mkdocs loads now. Will be testing tagging from here.

[sspencerwire]

This works. I'm going to post this to the documentation channel as I've got a screenshot to show you all as well. Essentially, after reinstalling the mkdocs-material extension from the available packages (i.e., the latest packages) then adding the below to the plugins section of the mkdocs.yml file:

  - tags

You then add this to the meta at the top of the file (shows entire file meta):

---

title: LXD Server
author: Steven Spencer
contributors: Ezequiel Bruni
tested with: 8.5
tags:
  - lxd
  - enterprise
---

The file is searchable by both tags using the top of the documentation search feature.

[NezSez]

Closing issues as resolved by the use of "Tags" for searching.