Opened 6 years ago

Closed 5 years ago

Last modified 5 years ago

#20232 closed enhancement (fixed)

Rewrite module doc of `LinearCode`

Reported by: jsrn Owned by:
Priority: major Milestone: sage-7.3
Component: coding theory Keywords:
Cc: dlucas Merged in:
Authors: David Lucas, Johan Sebastian Rosenkilde Nielsen Reviewers: Johan Sebastian Rosenkilde Nielsen, David Lucas
Report Upstream: N/A Work issues:
Branch: 9c82dcd (Commits, GitHub, GitLab) Commit:
Dependencies: Stopgaps:

Status badges

Description

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.

Change History (10)

comment:1 Changed 5 years ago by dlucas

  • Branch set to u/dlucas/rewrite_doc_for_linear_code

comment:2 Changed 5 years ago by dlucas

  • Commit set to 9cbca19e8c5888cad642ef2c9ea8cebe642dd3ac
  • Milestone changed from sage-7.1 to sage-7.3
  • Status changed from new to needs_review

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:

9cbca19Rewrote module documentation for linear_code.py

comment:3 Changed 5 years ago by jsrn

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

comment:4 Changed 5 years ago by jsrn

  • Branch changed from u/dlucas/rewrite_doc_for_linear_code to u/jsrn/rewrite_doc_for_linear_code

comment:5 Changed 5 years ago by jsrn

  • Commit changed from 9cbca19e8c5888cad642ef2c9ea8cebe642dd3ac to 9c82dcd0c3c1938e24de9c93d3e7d3850fc7f3af

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:

3b0140eA few more details on what a code is along with some keywords
1efb48eMore on "families" vs generic codes, and suggestions on [Abstract]LinearCode
9c82dcdSome polishing, and promote linear_code in documentation index

comment:6 follow-up: Changed 5 years ago by dlucas

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

comment:7 in reply to: ↑ 6 Changed 5 years ago by jsrn

  • Status changed from needs_review to positive_review

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.

comment:8 Changed 5 years ago by jsrn

  • Authors set to David Lucas, Johan S. R. Nielsen
  • Reviewers set to Johan S. R. Nielsen, David Lucas

comment:9 Changed 5 years ago by vbraun

  • Branch changed from u/jsrn/rewrite_doc_for_linear_code to 9c82dcd0c3c1938e24de9c93d3e7d3850fc7f3af
  • Resolution set to fixed
  • Status changed from positive_review to closed

comment:10 Changed 5 years ago by chapoton

  • Authors changed from David Lucas, Johan S. R. Nielsen to David Lucas, Johan Sebastian Rosenkilde Nielsen
  • Commit 9c82dcd0c3c1938e24de9c93d3e7d3850fc7f3af deleted
  • Reviewers changed from Johan S. R. Nielsen, David Lucas to Johan Sebastian Rosenkilde Nielsen, David Lucas
Note: See TracTickets for help on using tickets.