openldap: add introduction to install guide #119
Conversation
Describe what OpenLDAP is, what it does and who it is useful for.
how-to/openldap/install-openldap.md
Outdated
| @@ -1,4 +1,11 @@ | |||
| (install-openldap)= | |||
|
|
|||
| Lightweight Directory Access Protocol (LDAP) is a protocol used for managing hierarchical data. It offers a way to store, organise and manage an organisation's data such as employee accounts and computers. It facilitates centralised authentication and authorisation management. | |||
There was a problem hiding this comment.
It would be really good to include a link over "Lightweight Directory Access Protocol" to the official LDAP homepage or documentation for the benefit of readers who might want to know more.
how-to/openldap/install-openldap.md
Outdated
|
|
||
| Lightweight Directory Access Protocol (LDAP) is a protocol used for managing hierarchical data. It offers a way to store, organise and manage an organisation's data such as employee accounts and computers. It facilitates centralised authentication and authorisation management. | ||
|
|
||
| OpenLDAP is the open-source implementation of LDAP used in Ubuntu. It provides an LDAP server and a client to manage directory services. Thanks to its high configurability and flexibility, OpenLDAP can be tailored to suit various needs and is a pertinent choice for those with specific requirements. However, because of those characteristics, beginners sometimes find it difficult to apprehend or administer. |
There was a problem hiding this comment.
I see what you mean about the "negative" aspect of the final sentence. I always think in cases like this where a piece of software is not aimed at beginners, it's fine to say so, but then to solve the problem by providing a link to somewhere that they can empower themselves by learning what they need to know. I think you already partially solved this problem by including the link to our LDAP introduction page.
I think it's all in the framing, really. I would suggest making the final sentence part of the final paragraph, and rather than saying "beginners sometimes find it difficult to apprehend or administer", I'd instead frame more in the direction of "OpenLDAP contains some terminology and concepts that new users may want to familiarise themselves with before attempting to set it up." In this way, it acknowledges that it's not an easy/beginner topic, but doesn't assume that the reader will find it hard.
There was a problem hiding this comment.
Thank you for your detailed feedback! This sentence "OpenLDAP contains some terminology and concepts that new users may want to familiarise themselves with before attempting to set it up." doesn't have the negative aspect and it is perfect. I will make the changes as soon as possible!
how-to/openldap/install-openldap.md
Outdated
|
|
||
| OpenLDAP is the open-source implementation of LDAP used in Ubuntu. It provides an LDAP server and a client to manage directory services. OpenLDAP contains some terminology and concepts that new users may want to familiarise themselves with before attempting to set it up. Thanks to its high configurability and flexibility, OpenLDAP can be tailored to suit various needs and is a pertinent choice for those with specific requirements. | ||
|
|
||
| See [Introduction to OpenLDAP](../../explanation/intro-to/openldap.md) for a more detailed explanation. |
There was a problem hiding this comment.
| See [Introduction to OpenLDAP](../../explanation/intro-to/openldap.md) for a more detailed explanation. | |
| See {ref}`Introduction to OpenLDAP <introduction-to-openldap>` for a more detailed explanation. |
There was a problem hiding this comment.
We're using MyST markdown, so we can point to internal links using the {ref} role. This means that if a page is moved and the path gets updated, the links won't get broken (which is very handy!) so we try to take advantage of this formatting everywhere we can.
It works in the same way as the rST :ref: role but with a slightly different syntax. Anywhere you want to point you, you put an "anchor": in rST that's with .. _link-text-to-point-to: and in MyST it's (link-text-to-point-to)=. All the pages have an anchor at the top, and it simplifies maintenance a lot.
There was a problem hiding this comment.
Okay, thank you! I will make the change!
how-to/openldap/install-openldap.md
Outdated
|
|
||
| [Lightweight Directory Access Protocol](https://ldap.com/) (LDAP) is a protocol used for managing hierarchical data. It offers a way to store, organise and manage an organisation's data such as employee accounts and computers. It facilitates centralised authentication and authorisation management. | ||
|
|
||
| OpenLDAP is the open-source implementation of LDAP used in Ubuntu. It provides an LDAP server and a client to manage directory services. OpenLDAP contains some terminology and concepts that new users may want to familiarise themselves with before attempting to set it up. Thanks to its high configurability and flexibility, OpenLDAP can be tailored to suit various needs and is a pertinent choice for those with specific requirements. |
There was a problem hiding this comment.
OpenLDAP also provider a client library that is used by many many many applications in Ubuntu. For example:
$ apt-cache rdepends libldap2|wc -l
192
I suggest something like "It provides an LDAP server and a client to manage directory services, and also a library used by hundreds of other applications in their interactions with LDAP." Maybe Sally can wordsmith this a bit :)
There was a problem hiding this comment.
Thank you so much for your feedback! I'll make the change!
Add client librairies in provided services.
There was a problem hiding this comment.
Thanks for all your work on this @Sophie-Pages, this is a great improvement! We really appreciate your help in making the Server docs better :)
Describe what OpenLDAP is, what it does and who it is useful for.