Icinga2 documentation leaves much to be desired

Icinga 2
1

I would like to offer constructive feedback regarding my experience with this application. As an experienced IT professional who is relatively new to this particular platform,

I have encountered challenges with the setup documentation provided. Regrettably, I find the documentation to be deficient in both comprehensiveness and utility. It presumes a significant level of familiarity with the application, making it challenging for users who are not well-versed in its intricacies. Even the step-by-step setup instructions, which I am currently navigating, offer assistance to a limited extent, yet fail to facilitate the establishment of a fully operational server.

While I will refrain from providing specific instances, the overarching issue remains evident, prompting me to contemplate seeking an alternative solution.

While I appreciate the application’s capabilities, my time constraints prohibit extensive trial and error, necessitating a more comprehensive and accessible resource for guidance. If there exists supplementary documentation elsewhere that offers a more thorough elucidation of the setup process, I would greatly appreciate any guidance in that regard.

Please accept my assurance that my intention is not to convey criticism or offense but rather to articulate areas where improvement may be beneficial. Thank you.

2

I have encountered challenges with the setup documentation provided.

Thank you for your feedback - it’s always good to know how easily newcomers to
Icinga can get up and running, and if there are problems, what we can do to
improve things.

I will refrain from providing specific instances,

That is disappointing. Specific information about the steps you found
confusing, or unclear, would be very helpful in knowing what needs
improvement.

Please accept my assurance that my intention is not to convey criticism or
offense but rather to articulate areas where improvement may be
beneficial. Thank you.

Thank you also, and I really do encourage you actually to articulate the areas
where improvement may be beneficial.

We’re always happy to learn what problems people have run into, especially
when doing the basic steps of setting up Icinga, but so far your report
essentially says “I find the documentation to be deficient in both
comprehensiveness and utility” without pointing to where the documentation
is deficient, or in what ways you find its utility to be inadequate.

Please do consider taking a little more time to explain exactly where in the
documentation you got stuck, got confused, or otherwise failed to complete the
installation you were trying to do.

If the current documentation is not good enough, just saying “it could be
better” leaves us guessing at which parts need attention. Specific pointers
would help greatly.

Thanks,

Antony.

2 Likes
3

Hello,

I would second the statements made by Tony. I will go a bit further in details, with my own wishes regarding documentation.

It would be good to have:

  1. An overview document (10 - 20 pages max) that gives a high-level description of all available modules and resources available

  2. A nice presentation; the current format is not engaging for extensive reading

  3. PDF files to download with a nice format

  4. An index or quick search across all documentation

  5. Instructions on how to size the servers

  6. Tables of ports to be opened within Firewalls to allow communications between modules

  7. Best practice architectures

  8. All contents taught in the courses, basic or advanced, should be in the documentation

Thank you,

Jean

1 Like
4

Hey there, and also thank you for your feedback everyone!

We are currently working on some more comprehensive getting started docs, which aim to give an easy step-by-step installation guide for a simple single node setup, and also provide explanations for the different components we have.

In general, especially detailed, feedback from a beginners perspective is super valuable to us. Most of people working on Icinga have a pretty in depth understanding of the tool, which makes it super difficult for us to spot what kinds of things are not intuitive to new users.

@jeanm I’ll take your notes into the next planning milestone and see what we can do! Super good suggestions, thank you!

2 Likes
5

Here are some initial thoughts. I will continue to add to these in this post as they come to mind:

  1. Instructions on installation and usage for the different database options are fragmented. Parts of the instructions include guidance on all of the options, other parts only include one database. This should be more consistent; all of the different instruction modules should include direction on all of the database options.

  2. I feel like guidance on database customization in general during setup should be more thorough. The instructions make assumptions about the reader’s level of familiarity with database management and use.

  3. Another General comment: although it is quite likely that the reader is technically competent, given the vast number of disciplines within the IT umbrella, the instructions should generally be more thorough. For example, I am an IT analyst, but my skillset does not extend very far into database management, and other elements of this application. I know this suggestion is probably a bit vague, but there it is.

As I mentioned, I will continue to supplement this list as ideas pop into my brain.