Rewrite module doc of LinearCode

[johanrosenkilde]

The module docstring of LinearCode is vastly out of date, is too detailed yet too unspecific and loose, and also has formatting issues.

I suggest completely rewriting it. It is important for guiding new users to be sure to explain the difference between a LinearCode and a specific family subclassing AbstractLinearCode.

CC: @sagetrac-dlucas

Component: coding theory

Author: David Lucas, Johan Sebastian Rosenkilde Nielsen

Branch: 9c82dcd

Reviewer: Johan Sebastian Rosenkilde Nielsen, David Lucas

Issue created by migration from https://trac.sagemath.org/ticket/20232

[sagetrac-dlucas]

Branch: u/dlucas/rewrite_doc_for_linear_code

[sagetrac-dlucas]

comment:2

Hello,

I rewrote the module docstring of linear_code.py. To be more specific, I:

• completely removed the old docstring, which was, imho, focused on mathematical details and advanced specificities,
• wrote a very small definition of a linear code,
• explained the difference between AbstractLinearCode and LinearCode, and
• gave pointers to more detailed content (thematic tutorials).

I'm setting this to needs_review.

David

---

New commits:

9cbca19

Rewrote module documentation for linear_code.py

[sagetrac-dlucas]

Commit: 9cbca19

[johanrosenkilde]

comment:3

This is a much-needed improvement to sage.coding!

[johanrosenkilde]

Changed branch from u/dlucas/rewrite_doc_for_linear_code to u/jsrn/rewrite_doc_for_linear_code

[johanrosenkilde]

comment:5

Hi,

I've gone through the documentation and it's pretty good. I've pushed some suggested modifications to the text, in particular mentioning a few more keywords as well as emphasising the difference between generic codes and families. The latter lead to a slight restructuring of your description of AbstractLinearCode and LinearCode.

Let me know what you think, and we can co-review the ticket.

I also promoted linear_code in the reference manual module index, so that it figures first in its respective category. However, that lead me to thinking that perhaps some of this text should go there (not necessarily in this ticket)? What do you think -- where do people look?

Best,
Johan

---

New commits:

3b0140e	A few more details on what a code is along with some keywords
1efb48e	More on "families" vs generic codes, and suggestions on [Abstract]LinearCode
9c82dcd	Some polishing, and promote linear_code in documentation index

[johanrosenkilde]

Changed commit from 9cbca19 to 9c82dcd

[sagetrac-dlucas]

comment:6

Hello,

Let me know what you think, and we can co-review the ticket.

I'm fine with your changes. It's indeed better to emphasise the difference between generic codes and families, as I'm not it's standard terminology so the more specific, the better.
I also agree with the definition of encoding, dual codes, etc: these are very useful concepts which deserve to be defined here.

I also promoted linear_code in the reference manual module index, so that it figures first in its respective category. However, that lead me to thinking that perhaps some of this text should go there (not necessarily in this ticket)? What do you think -- where do people look?

I think we should left it as is: this file is supposed to be an index, as in any book, and when you're browsing an index, you usually expect quick access to the entry you're looking for - not some definitions. That's why I changed the name of the entry, from Linear codes to Generic structures for linear codes: with this new name, one knows exactly what to expect when one clicks on this entry.

Best,

David

[johanrosenkilde]

comment:7

I think we should left it as is: this file is supposed to be an index, as in any book, and when you're browsing an index, you usually expect quick access to the entry you're looking for - not some definitions. That's why I changed the name of the entry, from Linear codes to Generic structures for linear codes: with this new name, one knows exactly what to expect when one clicks on this entry.

That makes sense -- let's keep it. Let's think about whether we could leverage SageDays 75 for getting some input on the documentation. Some beginners might have valuable feedback.

[johanrosenkilde]

Author: David Lucas, Johan S. R. Nielsen

[johanrosenkilde]

Reviewer: Johan S. R. Nielsen, David Lucas

[vbraun]

Changed branch from u/jsrn/rewrite_doc_for_linear_code to 9c82dcd

[fchapoton]

Changed reviewer from Johan S. R. Nielsen, David Lucas to Johan Sebastian Rosenkilde Nielsen, David Lucas

[fchapoton]

Changed commit from 9c82dcd to none

[fchapoton]

Changed author from David Lucas, Johan S. R. Nielsen to David Lucas, Johan Sebastian Rosenkilde Nielsen