Documentation and naming: cleaning up the mess
Daniel and I identified several problems which can be regarded as major for a new user regarding to the documentation:
-
First of all, as we said quite a lot of times, coding theory thematic tutorial written by Joyner et al. seems completely insane. It jumps (first paragraph) from the creation of a generic Linear Code to (second paragraph) methods related to Duursma zeta function... Moreover, it lists almost every method in the library, talks a lot about GAP/GUAVA and gives an example of construction for every single code family. According to me, it is way too long and completely irrelevant. I suggest to completely delete it and replace it with an update version of what I did here, maybe without section IV.
-
In Joyner's tutorial, there is a complete section dedicated to bounds... Which have terrible names, and at least one of these (
singleton_bound_asymptotic
) seems completely useless. Some of these should probably be rewritten, as the code might be slow/weird/wrong, but for now I suggest we just rename these bounds to somehow sort them (like, I don't know, prefix all minimum distance bounds byminimum_distance
and so on) and make them user-friendlier. -
Last but not least, Reference Manual index page for coding theory has grown, and will grow even more in the future. It's already quite a mess, so I suggest we create some headlines to sort the links, like what have been done here.
Daniel and I feel this as a thing to do quite soon: if we start to email people about our new CT library when communicating on the Sage Days, and the first few things they see are these insane tutorial, the weird bounds and the messy index page, it probably won't help them being motivated about our work...
Comments (3)
-
-
reporter A quick update here:
-
reference manual index and thematic tutorial on how to implement new classes in the new API are positive reviewed.
-
rewriting of Joyner's thematic tutorial is done, and waiting for review
-
-
reporter - changed status to resolved
Done both in trac #19745 and #19897
- Log in to comment
I agree on all points. I would prioritise the three changes as follows:
For the bounds, remember Ticket 16393. I started working on it in Liege but never continued after that. It might be worthwile to pick up those shreds and push to the ticket...
Johan