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 by minimum_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)