MySQL Bugs: #103062: MySQL Replication extract from 5.7 is non-consistent with Reference Manual.

Bug #103062	MySQL Replication extract from 5.7 is non-consistent with Reference Manual.
Submitted:	22 Mar 2021 16:07	Modified:	6 Apr 2021 12:33
Reporter:	Jean-François Gagné	Email Updates:
Status:	Verified	Impact on me:	None
Category:	MySQL Server: Documentation	Severity:	S3 (Non-critical)
Version:		OS:	Any
Assigned to:		CPU Architecture:	Any

Description:
Hi,

In [1], we have the "MySQL Replication extract from the MySQL 5.7 Reference Manual".  The part of the manual that looks like matching this is [2].

[1]: https://dev.mysql.com/doc/mysql-replication-excerpt/5.7/en/

[2]: https://dev.mysql.com/doc/refman/5.7/en/replication.html

But when diving deeper in these, we can find discrepancies between the two.  The one I found is [3] (from the manual) and [4] (from the extract), but I guess there are others.  In [4], the information described from [3] is split in 2 sub-pages, and there is much more information about "Replication with Differing Table Definitions on Source and Replica" in the sub-page of [4] ([5]) than in [3].

[3]: https://dev.mysql.com/doc/refman/5.7/en/replication-features-differing-tables.html

[4]: https://dev.mysql.com/doc/mysql-replication-excerpt/5.7/en/replication-features-differing-...

[5]: https://dev.mysql.com/doc/mysql-replication-excerpt/5.7/en/replication-features-more-colum...

This duplication and lack of consistently is making it harder for the user to document themselves on feature.  Either duplication should be avoided, or both manuals should be consistent.

Many thanks for looking into this,

Jean-François Gagné

How to repeat:
N/A (documentation bug).

Suggested fix:
Extract for description: either duplication should be avoided, or both manuals should be consistent.

Looking more closely into this, the content might be the same, but the fact that everything is in a single page vs in sub-pages confused me.  And if I was confused, then I guess some other people might get confused.  If would be good to simplify this.

Thanks for the report
Bogdan

Posted by developer:
 
Thanks for the comments! As you said in the update the content is exactly the same, the extracts are created from the original source for the full manual. The extracts have been around for a while and my understanding is that they are created as a more lightweight and modular way for users to engage with themes in the reference manual, which is pretty large. The different page divisions are because the top level division of the material is higher for the extracts. So the build process creates subtopics where the same content in the reference manual would all be on one page. Personally, I think this helps make the extracts easier to parse and search, and helps reduce the cognitive load for users in the case of the extracts, which supports what I believe is their intended purpose.

I hope that explanation is okay! I don't think it's likely that many people will compare the extract directly to the reference manual in this way. So I think the benefits of the more modular structure outweigh the chances of confusion here, and we wouldn't change it for that reason.

Thanks for the reply Margaret.

> I don't think it's likely that many people will compare the extract directly to the reference manual in this way.

Allow me to try changing your mind on this.  I ended-up comparing the doc because I searched Google for "slave_type_conversions" (or one of ALL_LOSSY, ALL_SIGNED, ...) and the two first results are the reference manual and the replication extract.  Realizing that I was reading twice almost the same thing, this lead me to compare the docs and open this bug.

IMHO, the combination of having a replication extract and having different doc structure makes it hard, when arriving from Google, to see that these two are the same doc.  The different section numbering is also increasing this confusion.  I will let you decide is this is worth fixing (I could argue both ways).

Thanks.