Calc function articles in the wiki, differing opinions on details about presentation and formatting

I would like to hear broader opinions on how the Calc function wiki articles are presented.

There have been differing views on how the articles should be organised and formatted and I have acted as a sort of middleman. Regarding many of the topics of debate, I don’t have strong opinions. I mostly care about the technical side of things. That is why I think it is high time to involve the documentation team in general and also any interested Calc users.

I will mention some recent points of debate and would like to hear what people think works best.

In the article about the RANK function, the table with examples was made sortable and looked like this.

I received feedback that the sorting widgets look distracting, so I removed the sortability.

I then got feedback from the original editor saying that the intention was for the readers to essentially experience a simulation of how sorting affects the display of the ranking in Calc.

The last table showing example return values included text with strikethrough.

I received feedback that the strikethrough looked distracting, so I removed those texts.

I then got feedback from the original editor saying that the intention was to show what was incorrectly returned in LibreOffice versions 4.0 to 7.5.2 due to an implementation error.

In addition, I personally find the use of small text with the <small> element distracting and an accessibility issue (as seen in the Examples table). If I have to zoom in massively to make out what some text is saying, maybe it shouldn’t be presented like that.

Looking forward to hearing your opinions.

Hi, Ilmari

I’m convinced that original author’s intentions, in this case (Calc functions), are correct. He/She is thinking in better explaining the concepts for novice as well advanced users.

I would keep his formatting, and everything else, as he/she thought it in the first place.

The first post starts by some generic statement. In private communications in the past I have expressed some disagreement on some of the current guides regarding Calc functions wiki pages. Most of those pages by now have some content, so the original points I tried to mention back then would need much more work and multiple wiki editions now. Unfortunately, based on the lack of relevant replies in those past private communications, and based on the minimal feedback that this topic received until now, those general statements seem just some theoretical comment, perhaps some wishful thinking.

Now, regarding the specific wiki editions that were mentioned in the first post, it just happens that I am the “original author” of the wiki formatting that Ilmari removed.

For several days I’ve been awaiting for feedback on the specific mentioned editions in the first post. No objective reason was mentioned to remove the formatting. The editions seem to be subjective personal preference.

If someone would had contacted me to ask for objective improvements, I would had been open to explain the reasoning for the formatting that I used and, more importantly, to improve them.

LobaLuna summarized it correctly in the first reply. When I add some formatting, it is because I am thinking about diverse potential readers. It is not about some personal subjective artistic preference, and surely not to waste my time on some apparently random formatting.

The strike through is related to recent corrections to the RANKing functions in Calc (which I reported myself too, among others). After the modifications took effect, I could had removed the prior results for the examples in the wiki pages by replacing them with the new ones. But what about users of older versions (which are still in the wild, being actively used)? What about users of other implementations of the ODF standard? Do you want someone to report an error in the wiki, or to edit the page as if the newer results were to be wrong?

Instead of deleting the old results (which are still “valid” for most users), I used a common practice in most forums. In this case, I don’t want to make something “disappear” (especially when it is still relevant); instead, I want to communicate that there was something there and that there is something different now. I want to keep the old (still now and for several years relevant) information.

A new user will not care about the text that is formatted with strike through in this table, because the result that is clearly shown (just together with it) is valid and it can be reproduced with the very latest version of LO Calc and with the current examples in the wiki page.

I also don’t want to add details and explanations about the old results. Adding some reference note would be more distracting for most readers, unnecessarily. The strike through is enough for most readers to just skip it, dismiss it. OTOH, some reader that would notice that the current result is different in his/her own version of Calc (or with any other ODF implementation), would pay more attention to “that other result that is strike through”.

IOW, the strike through is enough but not more than needed for its purpose.

A potential improvement, considering its purpose, is to make the same old results smaller and with lower contrast against the typical background color of the “cell” in the wiki table. This additional formatting would be even less intrusive to a common reader, but would still be potentially useful for some other group of readers that can benefit of the presence of the old results.

Regarding the sorting features of the RANKing data table, it is also about the readers. It is an additional tool for someone that is having trouble understanding the different RANKing functions and how they work. Having a dynamic table can greatly benefit readers, because the RANKing functions provide a specific sorting order to unsorted data (generally speaking).

In order to understand the purpose of making the data table sort-able, you have to put yourself in the place of a reader that doesn’t know the RANKing functions and that is trying to understand them, with some difficulty.

In some cases, I have contacted wiki editors in order to improve wiki pages. I have made dozens (if not more) corrections to important mistakes regarding information in the wiki, and I have corrected typos and wiki formatting (so call “minor”) mistakes in the wiki too, always thinking about diverse groups of potential final readers.

Now I have spent some time writing this post (after I already explained it to Ilmari in private). Whichever negative objective point might exist to remove the wiki formatting, it has not been expressed to me, and I am not seeing it here either.

As a user, my own reaction is that the strikethrough text is confusing in the wiki context, especially when appearing in a table showing values. It is not confusing to me in a forum context. This is subjective, we can’t give objective views.

The relative importance between the normal text located in the same “cell” as the strike through text can be improved. I can reduce the contrast of the font (of the older values) against the background, and/or the font can be reduced in comparison to the other text in the same “cell”.

This is not different than UI areas in LO in which the Design team has decided similar methods (e.g. smaller font size relative to other text in the same dialogue).

Those formatting methods reduce the “distracting” point, without having to add more information, which would be detrimental, or removing the information completely.

With a relative smaller size and being strike through, the common reader will just dismiss the strike through text and move to important matters. The reduced strike through text will not impede the learning curve of the function, but will allow to other readers to understand the potential inconsistency (as already explained in my prior post).

Hi,

Just a note that we should take care of accessibility of our wiki. For example strikethrough is generally not read by screen readers and as such should be avoided (even more in table where it adds complexity when it’s not needed). The same is to take into account for contrast, font size, etc.
I suggest you have a look to the Wikipedia accessibility style guide here:

and try to stick with it when possible.
Cheers
Sophie

Unfortunately, the whole set of Calc Functions wiki pages uses wiki formatting to differentiate terms such as function name, function’s arguments, Calc’s options and menus…

Although I try to improve readability in some cases, it would not be realistic to consider the mentioned accessibility guidance for TDF wiki; at least not strictly speaking. In that sense, preventing the possible/potential use of any wiki formatting would only have negative consequences, as you would have to get rid of almost any_and_all wiki formatting that is being purposely used for all the Calc Functions wiki pages.

IOW, preventing the usage of any particular wiki formatting in TDF for the theoretical consideration of accessibility would only carry the negative effects without achieving any of its positive goals.

If the quality of important information is currently questionable, focusing on even more difficult goals is less realistic ATM.

Sophie was only talking about strikethrough in case of screen readers and low contrast and small text in case of low vision users. I don’t know of any other accessibility issues with the Calc articles.

Exactly, I didn’t ask to write 100% accessible content, but a least avoid the most problematic issues we know with accessibility.
Trying to be more inclusive in the design of the wiki content is also part of our overall mission.

Actually, I am such “low vision user”. When using a screen reader, how do you think the square brackets for function syntax is read? How a screen reader distinguishes between the normal text and bold text marking function arguments or settings, especially within the middle of a sentence? Do you really think that completely-blind users could understand the subtleties?

As part of a paragraph, you might have a setting:

Search criteria = and <> must apply to whole cells

and a “bc” template indicating a UI navigation path. A reader with some degree of visual difficulties could deal with all this in one way or another (including strike through text and diverse font sizes), but I very much doubt a blind user could use the wiki as its main source (or as third-level source for that matter, considering the amount of incorrect information).

Anyway, I expressed my reasoning (here in public and in private). I already used my own time much more than I am willing to for this matter, after I used my own time to improve the RANKing function wiki pages in the first place.

I am much more interested in actually doing things, and it is not frequent to see other wiki editors correcting serious mistakes or even typos, so when these specific editions were deleted, I cannot help but wonder. Why not directly contact me for improvements, instead of deleting the formatting?

For several days I awaited to see what exactly was wrong, and no one posted 1 negative iota. Instead of reverting back the deleted source text/formatting, I decided to post a reply. I still don’t know why there was a need to “middle” between some different opinion, instead of directly approaching me and asking for improvements. Suddenly there seems to be “something” negative to come up with.

I am willing to improve the potential distraction that Ilmari mentioned (and I would have done it without all this anyway) by improving the formatting, but considering the amount of serious mistakes that are left uncorrected in the wiki, I do not want to keep wasting more of my own time on this vague topic (going from some generic matters, to specific editions and back to generic comments); especially since the original source/reason for the deletion of the formatting is still not known.

Moreover, the same source of conflict was supposed to have some reason to delete the sorting format of the table. But there is nothing about it.

There are tons of incorrect and/or inconsistent formatting in the wiki. I see them every day. Even in new text that is just introduced to new Release Notes. It has been accepted and translated.

IMO, the deletion of the sorting features in that particular table are plain ignorance, and the distraction issue can be solved.

With NVDA on Windows, Preferences - Settings - Speech: Punctuation/symbol level: all.
On Linux with Orca, there is likewise a Punctuation Level in speech preferences. In the context of Calc function articles, a blind reader will know that they want to hear all punctuation.

You keep changing the subject. Sure, the screen reader will read it, but the point is whether the person / user / “reader” that is trying to learn about the function will understand the real meaning of each of the specially-formatted terms / words / phrases, and whether the intended information could be put in actual practice.

As I said, the several groups of target readers are in my mind when I use my time to edit a wiki page.

Are we really discussing 8 words with strike through? Where is that other opinion that triggered all this in the first place? Why is the sorting feature table on this particular function not appropriate? The reason given was “let’s keep things simple”. Really? That’s it? Am I really wasting my time because someone sees 7 small arrows and doesn’t understand their utility for this functions? I could mention a lot of things in the wiki that are very far from keeping things simple. Seven small arrows? Really?

Do you want to see “distracting” text? I have corrected bold formatting that was not closed, so a whole paragraph was bold instead of one word. Same with “code” tags that were not closed. That’s a distraction, for months and years, present on templates that propagated the “distraction” to many wiki pages. And yet, no one corrected such evident distraction. But now 8 specific words in a specific table are distracting?

Deleting the formatting was not a way to improve the page. This topic has not contributed to anything positive in any pragmatic way. If you agree to re-introduce the formatting and to (let me, or anyone else) improve it, then there is something (for me) to do.

I don’t see any “middlemen between 2 opinions” here, as the introduction to this topic claims. I only see 8 words with strike through (which has space for improvement in formatting), a specific sort-able table with complete sense for it to have it, and a lot of wasting my time on nothing. There are tons of much better things to do.

I would instead have them like

#N/A (since LibreOffice 7.5.3)

On the RANK warning/examples…

Personally, I would:

  1. Reword the Warning.
    • Especially removing lots of the extremely verbose info.
    • Just leave a warning about pre-LO 7.5.3 versions being broken.
      • And suggest UPDATING to the latest instead!
  2. Redo the “Examples” table.

1. Reword RANK's Warning

Current:

Reworded:

No need for them to know confusing (or extremely technical) details. No need for them to know Bug #154627. All they should know is:

  • It was broken.
  • Now it isn’t.

2. “Examples” Table

Instead, maybe just a simpler table where you:

  • Flip “Results” + “Explanations” columns
    • Puts “Formula” + “Results” right next to each other.
    • Then humans naturally read it like:
      • Here’s what I type in.
      • Here’s what I’ll get.
      • This is the reason why.
  • Simplify explanations
    • Remove a lot of the redundant “duplicates” + “ascending/descending order” wording.
      • You can split these into multiple tables with an explanatory sentence in between.
      • Cuts down on repeated repetition repeating in those Descriptions!
  • Put “likes with likes”.
    • Descending with descending
    • Ascending with ascending
    • […]
  • Ascending/Descending Tweaks
    • Same searched numbers in both groups.
    • Reordered based on return value.

Flipped “Formula”/“Results” column

Formula Returns Description
=RANK( -2; $A$2:$A$9; 0) 6 Rank of -2 in the given Data’s range in descending order.
=RANK( -2; $A$2:$A$9; 1) 1 Rank of -2 in the given Data’s range in ascending order.
=RANK( 19; $A$2:$A$9) 1 Rank of 19 in the given Data’s range in (default) descending order.
=RANK( 19; $A$2:$A$9; 1) 6 Rank of 19 in the given Data’s range in ascending order.
=RANK( -2; $A$2:$A$12; 0) 9 Rank of -2 in the given Data’s range (which includes duplicates) in descending order.
=RANK( 19; $A$2:$A$12; 1) 9 Rank of 19 in the given Data’s range (which includes duplicates) in ascending order.
=RANK( 17; $A$2:$A$12; 0) 2 Rank of 17 in the given Data’s range (which includes duplicates) in descending order.
=RANK( 15; $A$2:$A$12; 0) 5 Rank of 15 in the given Data’s range (which includes duplicates) in descending order.
=RANK( 14.8; $A$2:$A$12; 0) 7 Rank of 14.8 in the given Data’s range (which includes duplicates) in descending order.
=RANK( 17; $A$2:$A$12; 1) 6 Rank of 17 in the given Data’s range (which includes duplicates) in ascending order.
=RANK( 15; $A$2:$A$12; 1) 4 Rank of 15 in the given Data’s range (which includes duplicates) in ascending order.
=RANK( -10; $A$2:$A$9) #N/A -10 is outside the range of values in Data.
=RANK( 20; $A$2:$A$9) #N/A 20 is outside the range of values in Data.
=RANK( 4; $A$2:$A$9; 1) #N/A The value 4 falls within the range of values (of Data) but it is not listed in Data.
=RANK( 4; $A$2:$A$9) #N/A The value 4 falls within the range of values (of Data) but it is not listed in Data.

= = = = = = =

Then, I’d overhaul the entire thing, splitting it into smaller tables per category…

Simplified explanations

These formulas search Data (A2 through A9) for a given number:

Formula Returns Description
=RANK( -2; $A$2:$A$9) 6 -2's Rank in (default) descending order.
=RANK( -2; $A$2:$A$9; 0) 6 -2's Rank in descending order.
=RANK( -2; $A$2:$A$9; 1) 1 -2's Rank in ascending order.

Duplicates are included. For example, if we search Data (A2 through A12), 15 appears two times and 17 three times.

In descending order:

Formula Returns Description
=RANK( 17; $A$2:$A$12) 2 17's Rank. (Appears 3 times: A3, A10, A12)
=RANK( 15; $A$2:$A$12) 5 15's Rank. (Appears 2 times: A2, A11)
=RANK( 14.8; $A$2:$A$12) 7 14.8's Rank.
=RANK( -2; $A$2:$A$12) 9 -2's Rank.

In ascending order:

Formula Returns Description
=RANK( -2; $A$2:$A$12, 1) 1 -2's Rank.
=RANK( 14.8; $A$2:$A$12, 1) 3 14.8's Rank.
=RANK( 15; $A$2:$A$12; 1) 4 15's Rank. (Appears 2 times: A2, A11)
=RANK( 17; $A$2:$A$12; 1) 6 17's Rank. (Appears 3 times: A3, A10, A12)

#N/A” is returned if you search for a number that is not listed in Data:

Formula Returns Description
=RANK( -10; $A$2:$A$9) #N/A -10 is not in A2->A9. (It is in A14.)
=RANK( 20; $A$2:$A$9) #N/A 20 is not in A2->A9. (It is in A15.)
=RANK( 4; $A$2:$A$9; 1) #N/A 4 is not in A2->A9. (It is in A12.)
=RANK( 100; $A$2:$A$16; 1) #N/A 100 is not in column A (or even in the table at all).

= = = = = = =

This drastically cut the explanations down from ~200 to ~150 words.

The 24.2 Manual should be brought up-to-date with the latest info/results as of LO 24.2.

So I would:

  • Leave a warning in, informing users that this function in LO <7.5.3 gave wrong info.
    • Then purge that warning after 7.5 is relatively old.*
  • Only show results as they appear in 24.2.

I wouldn’t muddy Help with results from 7.5.2 AND 7.6 AND 24.2 AND (who knows what other End-of-Life versions + old/already-resolved bugs + potentially buggy documents).

(* Maybe still keep warning around for a few years after LO 7.5’s End-of-Life.)

Hmmm, well these “serious mistakes” or “incorrect/inconsistent formatting” should be worked on and be made incrementally better (and/or completely rewritten). :slight_smile:

Take a bite out of it at a time.

As long as the Wiki/User Guides are moving in the right direction—by getting more correct, readable, consistent, and Accessible—that all sounds great in my book! :slight_smile:


Side Note: If you want to maintain (and update) documentation, I’d strongly recommend listening to this fantastic podcast interview:

He was a Technical Writer at NVIDIA for many years, and described some best practices + how to keep documentation up-to-date.

One of the key points was also:

  • Dating the last time an article was updated/revised!

This would help prevent lots of ancient cruft building up too… For example, we wouldn’t want to clutter and confuse users with old 4.0/7.4 warnings.

(Instead, it’ll be better to say: “Hey! Users of LO 4.0! What are you doing in 24.2 Help? Update already! It’s your fault if you have that bug from 10+ years ago!” :stuck_out_tongue: )

(That option changed names 4 years ago? Let’s give it the 24.2 name already and purge all references to the old! If users wanted the 4 year old name, they can dig up that old User Guide!)


Side Note 2: Another fantastic resource is the amazing book:

  • “Oxford Guide to Plain English” by Martin Cutts

especially one of my favorites:

  • Chapter 8: Using Vertical Lists

For example, I applied many of those concepts to “pull the redundant info” out of the Descriptions.

This lets you only say it ONCE, instead of repeating every single time the explanation is given.

Here is one of the examples given in the 5th Edition of the book: