From cda99a09136dd90dde298bf65afbc7b8a95ed250 Mon Sep 17 00:00:00 2001
From: Pekka Paalanen <pekka.paalanen@collabora.com>
Date: Fri, 14 Oct 2022 12:43:27 +0300
Subject: [PATCH] readme: add Using section

I believe this is what we intended, and it is what I want.

It could lead to duplicating low-level API in high-level API at first,
but once we start seeing DisplayID in the wild, the high-level functions
need to start looking into both EDID and DisplayID APIs to deliver the
desired information.

Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
---
 README.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/README.md b/README.md
index 357b801..3076d86 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,19 @@ Goals:
 
 Documentation is available on the [website].
 
+## Using
+
+The public API headers are categorised as either high-level or low-level API
+as per the comments in the header files. Users of libdisplay-info should prefer
+high-level API over low-level API when possible.
+
+If high-level API lacks needed features, please propose additions to the
+high-level API upstream before using low-level API to get what you need.
+If the additions are rejected, you are welcome to use the low-level API.
+
+This policy is aimed to propagate best practises when interpreting EDID
+and DisplayID information which can often be cryptic or even inconsistent.
+
 ## Contributing
 
 Open issues and merge requests on the [GitLab project].
-- 
GitLab