xDrip+ Manual updates, and more

[ANDREAPIPPI]

HI.
I discovered the xDrip+ manual here https://xdrip.readthedocs.io/en/latest/ a few weeks ago, and I was amazed by the enormous work done by Navid in collecting, checking, smoothing and graphically homogenizing a myriad of information previously scattered in the issues, discussions and other.
I really appreciate that, but I would like to suggest a few small changes that could make it more comfortable for many people.

1- First of all, its existence is not very evident, I only found it thanks to serendipity, so I guess many xDrip+ users don't know about its existence...
2- the index can only be found by clicking on the three parallel horizontal lines at the top left, and it shows the chapters first, by clicking which its paragraphs appear on the right.
Since this document is continuously updated, to check if and which paragraphs or chapters have been modified since my last check, the only way I have found is to note each date on my check, and for a new check open again the last page of each of them!
This is not the best system, IMHO.
If there isn't already another simpler system that I'm lost on, I'd suggest changing the index like this:

a- unique index table, showing each chapter "and" its paragraphs.
b- each chapter and paragraph title is a link to the relative web page, as it is now, but also adding the date of the last update to its right.
In this way it is no longer necessary to check all last pages (image 1).

c- possibly, when inserting a paragraph, the update date should be made evident, for example with a very different color, and/or with an italic font, and/or in bold or with a larger size (image 2).

d- this is very important: the modified texts/images should be made evident with for example a clearly visible vertical line beside the modifications (image 3).

e- last suggestion, which however I fear is utopia: it would be nice to have an updated downloadable pdf file, let's say.... once every 6 months... (I belong to the category of those who prefer to read a paper text rather than an electronic one)

My suggestions are based on a long experience working in civil aviation, where for each type of aircraft we received many updates every month, and what I have just suggested was necessary to avoid losing modifications that could be of vital importance also for the safety.
However, it's just my opinion.
And, as I said, my biggest thanks to Navid or whoever came up with something that 99.99% of applications, even much smaller than xDrip+, lack.
Well done!
Andrea

[Navid200]

That guide is managed by @psonnera
This other guide is managed by me: https://navid200.github.io/xDrip/

Both guides are indexed by Google. So, if you search for xDrip info, you will find one or the other or both.

I would like the xDrip wiki to point to these two guides and have submitted that suggestion to the developers already.

[psonnera]

I will re-read this this evening and see how it can be made, the fastest way I thought was to look for the change log that highlights main differences. https://xdrip.readthedocs.io/en/latest/changelog/ Since I'm rewriting the Nightscout documentation (and I need to update it with Serendipity) I might also migrate xDrip+ to Sphinx. Thanks for the feedback.

[Navid200]

From my perspective, the guide is supposed to help those who are in a panic looking for information. Imagine a mother who is tired late at night and wants to go to bed; but, because her xDrip has stopped showing her child's readings, as a follower, she needs to get it sorted out right away.

Helping that mother is why I put together my guide. It needs to be easy to understand and it needs to help fix the problem.
As a requirement for me to be able to maintain it, it also needs to be easy to manage.
A few years ago, I used to type an answer, on facebook, and find out in a few days that I have to answer the same question again. I knew that I had gone into detail a few days ago answering the same question. But, it wasn't easy to find my previously entered text.
That's how my guide was born. I decided to create pages to contain such answers. Then, I wouldn't have to keep writing the same thing over and over again because I could easily find the answer and use a link to point to it.

I see all the time people taking an image from my guide and attach it on facebook to their post to answer a question instead of placing a link to the page they copied it from.
So, the real world is a place with all sorts of people with all sorts of different priorities and objectives and values. That's life.

I am not going to go out of my way to make life easier for those who want to copy and not give credit where credit is due even if it may help someone who has no alterior motive.

I can see how useful what you are asking, showing the change date, can be. But, that would be useful to someone who has looked at everything already and only wants to know what's new. The character I described above who needs to go to bed but cannot does not have time to read the entire guide. If xDrip works for her, she has so many other chores in life that she prefers not to have to learn anything new about xDrip if she doesn't need to!

My guide has a lot of shortcomings that I am working on.
All feedback is greatly appreciated.
I have to prioritize and keep at it.
Please provide feedback when you can.
Many thanks

[ANDREAPIPPI]

I would like the xDrip wiki to point to these two guides < Navid200

Thank you Navid, but I would suggest to possibly spread this info/link in all xDrip+ pages or at least in the main pages, and a very evident way, not mixed to a lot of other items, but standing alone.
I mean something like a banner in all issues, discussions and whatelse regarding xdrip+,
This could also avoid for you and other programmers/collaborators the need to point many times to that link .

Thanks for the feedback < psonnera

Thanks a lot to you for your work, you are very welcome.
In my first message I forgot to say that the manuals whose I was speaking of were technical, so very important for the aircraft and people safety.
So, even if told everywhere that xDrip+ IS NOT for medical use, I defiance all of you to say you never used xdrip+ to correct your CHO/U.I., or modify insulin bolus and so on.
So IMHO the "exact, full, updated knowledge" of what is possible or not, what is safe or dangerous using xdrip+ should be widespread to every user.
As I told, just my opinion.
Andrea

[psonnera]

@ANDREAPIPPI as a caregiver I'm extremely cautious on how I use xDrip+. Safety comes from knowledge and unfortunately it's not within everybody's reach. This is why the disclaimer on using xDrip+ is so strong. Can you give me hints on where strong disclaimers should be added? Up to now, most of those who managed to hurt themselves were using Libre sensors with bridges, one old event went to the FDA ears and generated a strong warning from the vendor...
I'll add a revision page as your table above. But first I need to complete the Nightscout documentation rework and then catch up with our tireless developers

[Navid200]

So, even if told everywhere that xDrip+ IS NOT for medical use, I defiance all of you to say you never used xdrip+ to correct your CHO/U.I., or modify insulin bolus and so on.

That is irrelevant.
What I do personally has nothing to do with what we are talking about here, the official position of the xDrip developers.

xDrip is not approved by the FDA. Therefore, no one should use it for any dosage decisions. That's why everyone is expected to acknowledge that as soon as they install xDrip and open it for the very first time, or else they will not be able to use it.
If anyone uses xDrip to make dosing decisions, they are clearly doing something we have told them not to.

There is nothing we can do, with an open source app, to change that requirement, no matter how much information about safety we provide to users.

Nevertheless, we are providing more and more information in the guides to help users. That is the only reason those guides exist, to provide information about xDrip.

[ANDREAPIPPI]

Navid200
From my perspective, the guide is supposed to help those who are in a panic looking for information. Imagine a mother who is tired late at night and wants to go to bed; but, because her xDrip has stopped showing her child's readings...

It happened to me too, some time ago, right at the beginning of my use of xDrip+.
I forgot a step while installing a new sensor and nothing worked.
The actual manuals didn't exist, and being stressed by what was happening, I couldn't find what was the right procedure, in the sea of links related to xDrip+ (and, sorry Navid, Google only created more confusion).
Luckily I always follow the proverb "try and try and try it again", so I finally solved it.
But if there had been a single, complete manual, including ALL the meanings and rules of the infinity of procedures and possible settings, it wouldn't have been a problem, just as it wouldn't have been a problem for that mother in a panic because she was unable to receive her child's BG readings.
The only "procedure" to remember would have been...
"go to the link that you have among your "favorites" or that you can find on any page of the xDrip+ site, check the index, find the chapter that suits your needs and click on it.
You will find the solution there!"
Easy, isn't it?
This is precisely the purpose that I wanted to suggest with my proposal, nothing else, to make available to everyone, absolutely everyone, even the mother in a panic, the immediate answers to doubts, procedures and information, at a single link easily available everywhere.
In each page there should be a "manuals" link, so that whatever the question, doubt, need, opening any page related to xDrip+ you will find the link to the solutions.

Just to understand, what is the reason for having two manuals?
If they were merged into one everything would be even easier, in my opinion.

And I suggest to insert in manuals a stronger "warning" , with the message "xDrip+ is not for medical use!".
E.g. a banner with bold white text on a deep red background, which will be very noticeable since this color combination is not used frequently or ever in xDrip+ (see image-1 as an example).

This should be at the top of each chapter / paragraph in both manuals, after the title line, leaving of course the detailed disclaimers already there.

I hope this clarifies what I meant by opening this thread.
I'm not an English speaking man, so please forgive my bad wording.
Andrew

[Navid200]

Just to understand, what is the reason for having two manuals? If they were merged into one everything would be even easier, in my opinion.

We didn't decide to have two manuals.
I created my guide quite a while ago.
I have no experience with Libre. Nor with watches other than BlueJay. Patrick does and many other subjects, like AAPS, which again I don't know much about.
So, Patrick, who was already providing support for those subjects and more, created his guide.

Why we have not merged the two together?
There is not one individual, interested in documentation, who knows everything there is about xDrip.
So, if we merge the two together, one of us will have to be the overseer. That, in my opinion, hurts more than helps.
I want us to spend time on what we need to do as opposed to waste time on administration.

There are subjects neither of us currently covers. I have no problem with even more people providing their services to help users.
On surface, if you only look at it idealistically, only from the user perspective, of course, it is better if there is only one guide.
But, let's be realistic. Let's say I am responsible for both guides. Then, there will be material in the guide I am responsible for that I don't know anything about. That has disaster written all over it!
Currently, I know the reason for every line in my guide. I do sometimes forget to update something for a while. But, that is very different than not knowing anything about a subject included in the guide.

Let's say I get into an accident and am hospitalized for a year. During that year, currently, only a part of our documentation will be affected.
But, if we merge the guides, that will be a different story.
That's why I am even OK with some overlap between the guides. If several guides cover the same thing from the perspective of different providers, as long as they are all correct and not outdated, I don't have a problem with that.

Let's say a user sees in Patrick's guide that xDrip does not support Android 4 any longer. But, they see in my guide that xDrip supports Android 4.
They can open a discussion here and tell us. That will be a great feedback for me to fix that error in my guide.
But, if we only had one guide, and it had an error like that, wouldn't that be harder to detect?
I guess I am bringing the community into this. The community can participate and help us improve the guides by providing feedback as you are doing now.

Thanks

[ANDREAPIPPI]

Hi Navid, thanks for the detailed analysis, and of course I agree.
But my interest is more focused on the rest of the discussion...
What do you think of my proposal?
It can be useful?
Possible?
Or does it add too much workload?
I would like to know what is your opinion, as you know I'm just a user and I can't know the real difficulties of changing even one word in a sentence.
Andrew

[Navid200]

If by your proposal you mean to add a warning not to use xDrip for dosing decisions, that's already in the app.
And it is in the guides. For example here: https://navid200.github.io/xDrip/docs/Requirements_page.html

[ANDREAPIPPI]

Sorry Navid, I disagree.
This is not a warning, it's mainly a lengthy letter of intent, necessary to legally cover github and the app's authors for civil and criminal legal liability, due to the consequences of misusing the app.
What I propose is....
something like a flashing light in the dark night, which catches the attention, can't be unseen, doesn't annoy nor is ignored because it's too long, so it does its job, i.e. warn users that this it's not a video game.
Perhaps this side-by-side comparison (same width) shows better what I mean...

I'm afraid you took it personally and focused only on this part of my proposal, which is not that important to me.
It is not so, what I propose is more for Patrick's use, and is not limited to the warning, but mainly to the organization of the manuals, (his manual, if you prefer) so
as to make them immediately and easily available and consultable
for any user who needs help
I hope I was clearer.
Andrea

[Navid200]

I responded to offer my opinion because you tagged me.
But, I am the one who tagged Patrick in this thread since he is directly involved with documentation.

I will stay out.

[psonnera]

@ANDREAPIPPI I don't see anything against this warning in xdrip.readthedocs.io. My only technical difficulty is that I'd like it to show on top of the left menu rather than on top of each page. Since the doc in written with mkdocs, I need to find a way to customize it though... and there I'd need help.

On the other hand, as we've discussed before @Navid200:

So, if we merge the two together, one of us will have to be the overseer.

No. In technical documentation people can work in their domain and leave alone other people's domain.

During that year, currently, only a part of our documentation will be affected.
But, if we merge the guides, that will be a different story.

Same than above. No. Multiple contributors can work independently.

Then, there will be material in the guide I am responsible for that I don't know anything about.

Then you wouldn't be responsible for it or only reference the work from someone more knowledgeable than you are. No problem.

What the main point is, and I've discussed that with other documenters is the audience. You can't cover the full audience. You can try to make something foolproof you'll always find someone not able to understand it. Navid's guide is covering many FAQs that get handy for helping answer some frequent questions for a certain time, but also full sequenced pages to explain a process.

After I had been using xDrip+ for a few years, I just couldn't find the bottom of it and that started my challenge: what is xDrip+ and what's behind all these menus and sub-menus. Can I create a full coverage of xDrip+ (of course no), like a full technical reference? And also, can I explain logical sequences for complex setups like Libre sensors with bridges and OOP algorithms, smartwatches, etc... So you see, it's about the audience.
Note: it took me months of digging into Gitter, Github, Facebook, internet old pages, asking people, devs, taking screenshots, correcting errors, apologizing when I wrote something inaccurate before I could bring this documentation to life. It's not as good as I'd like it to be but it's better than nothing.

But I would be glad if there was a way to merge the efforts to avoid diluting them.
As I don't want to rewrite other people's work (it's not my IP) I usually ask them before. Can I link your work? Can I rewrite it? Can I copy it? So at the end it's a patchwork, and that doesn't satisfy me.
The guy who opened this repo (https://github.com/xdrip/xdrip_docs) wanted it as a collaboration point. It didn't happen.

I would have no issue dropping it to contribute to someone else's repo if it's structured enough to cover all. Different audience.
But from my Nightscout experience I've learned to accept that different people do documentation differently and unless they have a clear indication of what to do from someone telling them what's expected from them, it will end up in different documentations...

Now I need to fix Nightscout and I'll put xDrip+ on standby for a while. But I'll be back. All PRs are welcome. Always.

[ANDREAPIPPI]

I'm sorry Navid, that wasn't my aim.
The documents currently available are yours and Patrick's, so you are more than eligible to comment and participate in this discussion.
And as I said, I would like to know what you think about the topics I indicated at the end of my previous post.
Please.
I'm not an expert, but I'm certainly a practical man, so I know I can be right or wrong on this matter, but if no one gives his opinion, I'll never know.
I'll wait for you, Navid, come on.
Andrea

[psonnera]

@ANDREAPIPPI tips to restructure the documentation is something I need help with. I don't like the way it's structured. Your opinion counts.

[ANDREAPIPPI]

Patrick, even if I'm not an expert, I'll give my opinion, if you wish,
Have a good job with nightscout!
Andrea