[DOCS] Preliminary work to split Infrastructure and Logs monitoring into two books #581
Conversation
|
Hi @elastic/infrastructure. Could I get a review on this, please? Docs build can be seen here http://stack-docs_581.docs-preview.app.elstc.co/guide/en/infrastructure/guide/master/index.html |
There was a problem hiding this comment.
I don't agree with this approach. This layout seems confusing. It duplicates a lot of content and forces the user to jump around if they're only using one solution:
It seems like this PR did 90% of the work, but left out the last 10% which is the actual "splitting" of the book. I thought we agreed to split the content and move on to some sort of TOC/navigation solution? I know we've had a lot of discussion around https://github.com/elastic/observability-dev/issues/14, but this is not one of the solutions we discussed.
|
@bmorelli25 My understanding is that this PR explicitly says that is not closing the issue, but just providing the starting point of it. Anyway, the comment raises another concern: if the intermediate state is one that we don't want published, we may either continue the work in the same PR or group the changes in a feature branch. |
|
Ultimately, @Titch990 owns this content. If y'all decide to merge this as-is, that's totally cool with me. If we decide not to merge this yet, I don't think we need a working branch. This PR is only a few lines away from being "done". My main concern is that the Kibana docs redesign is on track for 7.5. So by then, we need somewhere to put all of the Observability UI documentation.
If we're not going to follow the original plan, that's fine, we just need to make sure to involve |
|
@bmorelli25 Sorry, perhaps I wasn't clear. I would really have preferred to address this after: (a) We have solved the TOC navigation issue. But . . . I'd started this work before I realised the importance of these other two things and how essential they were for the final implementation. So I needed to park it neatly somewhere, and I realised I could complete a partial implementation. I can hold off merging this if you think it makes things worse. But I thought it made things a bit better, and closer to where we need to be. We now have separate introductory topics for Metrics and for Logs, whereas before they were mixed in one topic, which sometimes referred to only Metrics and sometimes to both Logs and Metrics. There are some changes under the hood, but that's actually the main change here. Everything else is as-is. Integrations need to be referenced by both Logs and Metrics, so don't belong in either the Logs or Metrics "books". And the first ones are coming soon, so need a place to go. With the navigation situation as it is at present, I didn't want to add yet another "book" for Integrations, then have to provide confusing cross-book links that will definitely need to be followed out and back in a basic user journey. My (very) short term plan is to keep the one book for Logs and Metrics, and add an Integrations section in this "book". Then I can split the "Setting up" topic (that's hard to split at present) into topics for Metrics and for Logs, each referencing the appropriate content in the Integrations section. Then, I can make separate sub-sections for the Metrics and Logs content. I really want to hold out splitting this into separate books until the navigation issue is resolved, but it will be ready to split as soon as it is. I wasn't aware of the timescale for the Kibana docs redesign, nor that it would mean the existing logs and metrics sections would need to be moved elsewhere immediately. If that is the case, I don't think it's a big deal, because I can simply swap the placeholder topics in this book with the current set of Kibana topics. So instead of stub topics in this book that reference the fuller descriptions in the Kibana book, the stub topics will be in Kibana and the fuller descriptions will be here. So now all I need to do is chase up the timescale for the improved navigation solution. As far as I can see, there has been no action on that issue yet. |
|
So, @bmorelli25 @andresrc. What do you think? My gut feeling is to publish this, add an Integrations section as required by https://github.com/elastic/observability-dev/issues/307, then split the rest into separate Metrics and Logging sections. With that in place it will be easier to split the "Set up" section in a way that's intuitive for the user, and will work with the integrations as they are produced. The Kibana orphan topics will also have an obvious home. Publishing this as is, while not ideal, unblocks several other tasks, and reduces the dependence on a speedy solution for the navigation issues (although I shall still keep plugging away at that, because it's still a problem for the rest of Observability too). |
I can see why you'd want to go this route, but it isn't the plan that was decided upon in elastic/observability-dev#14. I'm not married to the plan we came up with, but if you want to make changes like this, we need to discuss them with the right people first. My fear with this plan is it will further entangle these docs. Right now, the books are small -- it's an easy separation to make. The longer the content is able to grow together, the more entangled it becomes. Adding sub-sections and parts for Metrics/Logs will further that problem. In addition, we end up with a weird mix of some Observability docs together and others separate.
I think the problem with this is you're trying to solve our navigation issue with the structure of the docs. That isn't the right approach for our doc architecture. I know our nav isn't perfect right now, but it's something we have to live with. |
|
@brandon asked me to weigh in on this discussion because I've been involved in logs and metrics since the beginning...even before the apps existed. TBH, I'm on the fence as to whether this content belongs in a single book or two (mainly because the book paradigm is wrong for online content). If you're going to put everything into one book, though, a flat structure with the current level of repetition is problematic. The relationship between topics needs to be obvious when users look at the TOC. Flipping through topics one after another that contain a lot of duplicated content, but vary slightly, is not a great user experience, IMO, especially if it's expected that some users won't be running both UIs. What I'd really like to see is a structure that's organized around user goals with content that describes how users achieve those goals. It would also be good to see how the content in the Kibana docs (which I assume you're moving) fits into the content that you have here. I suspect the flat structure will not scale. I learned the hard way with Beats that having a structure that scales (even when you have a small amount of content) is pretty important. I'd suggest developing an outline that includes the content we have now plus all the content that needs to be written. This might help you avoid some rework in the future. It is a major pain to reorganize asciidoc content because the hierarchy is not decoupled from the content. If you can get the structure mostly right in the beginning, it will save you a lot of rework later on. |
Titch990
force-pushed
the
MJ-inframon-split
branch
from
f67204d
to
6a10141
Compare
I couldn't agree more!
This is exactly what I am trying to do. However, it appears that this split needs to be done first.
Not directly related to this pull request, I know, but I wonder if there is something we can do to help ourselves? Firstly, let's assume that each asciidoc file corresponds directly to one online topic. I know that's not always the case, but it is usually, so let's pretend. Within a topic, the reader doesn't care what the the heading level numbers are for the topic heading or the section headings. They simply care that there are headings. The topic heading helps them decide if the topic is relevant to them. The section headings divide up the content and make it easier to read or to scan. The topic heading needs to be a proper asciidoc coded heading, at the appropriate level, because as you say, the heading level determines where in the hierarchy the topic is located. But what if we could define some other style for the section headings (even a simple bold would be better than nothing)? The section headings just need to stand out from the body text. They don't need to be an actual heading style. Then, if the content hierarchy changes, the only thing that needs to change is the level of the topic heading. The section headings can stay exactly as they are, because they are not heading levels. |
Titch990
force-pushed
the
MJ-inframon-split
branch
from
3b5a171
to
64cd1ba
Compare
|
OK, we've decided to go for the full split, so this is now part of a multi-repo change (see elastic/observability-dev#98). DO NOT PUSH UNTIL EVERYTHING IS READY. |
…ting Started topic
|
Note that this is one of four linked PRs, which need to be merged together to avoid build failures. #581 (this one) DO NOT MERGE UNTIL EVERYTHING IS READY |
|
Can you please assign @zuketo as the reviewer here since it pertains to info architecture changes? |
|
@elastic/logs-metrics-ui Can I have a review please? Note that this is one of four linked PRs, and this does not build on its own. Because it doesn't build in isolation, I can't provide a link to the output for review, and because of the changes and renames, it's hard/impossible to review properly from the sources. However, I think there is value in a proper review of some of the changed topics. So I've done screenshots of the output from my local "everything together" build. Here's what there is and here's what I think is helpful to review (some topics are unchanged except for the location). The screenshots are here: https://drive.google.com/open?id=18hyRbxgh80ITyLXoQT4Z82P7k2zmaa6n
Outstanding changes.
|
|
@zuketo feel free to review and comment if you want to. However, this work is holding up other docs work for the 7.5 release. So if we are going to revisit the decision to go ahead with the split, that decision needs to be made promptly, so I can pull this and tackle other outstanding issues in a different way. |
There was a problem hiding this comment.
Thank you for tackling this and thank you for providing the convenient screenshots!
I don't assume to understand the overall docs reorganization effort, which is why I mostly looked at the aspects of technical correctness and consistency from the Logs UI perspective.
Also keep in mind that I'm not a native speaker, so I might be totally off on language-related comments.
I left some inline questions and suggestions below.
| [float] | ||
| === Enable modules | ||
|
|
||
| However you install {beats}, you need to enable the appropriate modules in {filebeat} to start collecting logs data. |
There was a problem hiding this comment.
This is not necessarily true and contradicts the previous paragraph. For custom log setups users would set up the appropriate inputs and configure some processors. The modules merely provide pre-packaged sets of such configurations.
There was a problem hiding this comment.
This content predates the split which is the focus of this PR. Raised #646 to address it.
| // ++ The instructions there explain how to enable the module. Below, we enable more stuff. | ||
| // ++ What about if you are using Cloud? Is anything different? | ||
|
|
||
| To populate the *Hosts* view with logs data, enable: |
There was a problem hiding this comment.
There are no "Hosts", "Docker" or "Kubernetes" views in the Logs UI. Depending on the available metadata it provides links to such views in the Metrics UI.
| [float] | ||
| === More about container monitoring | ||
|
|
||
| If you're monitoring Docker containers or Kubernetes pods, you can use autodiscover to automatically change the configuration settings in response to changes in your containers. |
There was a problem hiding this comment.
| If you're monitoring Docker containers or Kubernetes pods, you can use autodiscover to automatically change the configuration settings in response to changes in your containers. | |
| If you're monitoring Docker containers or Kubernetes pods, you can use autodiscovery to automatically change the configuration settings in response to changes in your containers. |
| * Appropriate {beats} shippers (version 6.5 or later) installed and enabled on each system you want to | ||
| monitor | ||
|
|
||
| If your data uses nonstandard fields, you may also need to modify some default configuration settings. |
There was a problem hiding this comment.
nonstandard is spelled differently below. Which one is the correct spelling?
There was a problem hiding this comment.
Thanks for investing so much effort. The sentences about setting up docker and container logs now make more sense.
There's a few instances of "Logs monitoring" and "non-standard" left, but since this is about the split I imagine you want to address the content improvements on a different occasion.
|
Jenkins retest please |
|
@weltenwort I thought I got all the instances of non-standard. I found another and nuked it! I think for now I'll stick with "Logs monitoring" throughout. The name of the app is the "Logs app" according to the marketing guide, and we also have the "Metrics app" and "Metrics monitoring guide". I'm happy to revisit if anyone feels strongly, but at least for now, we are consistent. |
|
I've talked with @Titch990 and we understand the CI failure that is on this and will handle it after merging. This is one of those unfortunate times when CI is causing us a fair bit of trouble because we can't link changes across repos. |
|
I know this doesn't build. It's part of a bigger inter-repo change and it won;t build until the other changes are made too. |
…nto two books (#581) * Partial changes to split Metrics and Logs content * Partial changes * More changes * That's it for now, I think! * Separating out logs and metrics installation. * Starting the move/rename for the split * Partial checkin, more doc moves. * Fixing an invalid link * More changes for the split * And another change for the split. This one to fix the link in the Getting Started topic * Addressing review comments * Couple more things arising from review comments
…nto two books (#581) * Partial changes to split Metrics and Logs content * Partial changes * More changes * That's it for now, I think! * Separating out logs and metrics installation. * Starting the move/rename for the split * Partial checkin, more doc moves. * Fixing an invalid link * More changes for the split * And another change for the split. This one to fix the link in the Getting Started topic * Addressing review comments * Couple more things arising from review comments
Partial implementation of https://github.com/elastic/observability-dev/issues/98.
For now, I've left the installation section as one topic as it doesn't seem sensible to split it then recombine it as a result of the integrations work, at least not before we have a clearer idea of the overall Observability documentation design in this area (in progress as https://github.com/elastic/observability-dev/issues/14).
Therefore, I've also left Infrastructure and Logging as one suitably named "book" for now, which we can split later.
Related issues https://github.com/elastic/observability-dev/issues/378 (the diagrams need to be updated). Since that issue is slightly wider, and covers a bit more than just splitting Metrics and Logs, I've just duplicated the existing diagrams for now in the two split topics.