On Friday, December 5, 2014 1:35:09 PM UTC+1, Fredrik Johansson wrote: > > On Friday, December 5, 2014 1:08:14 PM UTC+1, Jori Mantysalo wrote: >> >> >> Having documentation arranged by technical implementation is also bad. >> Having TESTS-section shown for normal user is bad. Having is_lattice() on >> different page that is_meet_semilattice() is bad. >> > > Seconding this. >
I've just seen this, sorry for being late. This topic of "improving documentation" is coming up over and over again. Last time, I've posted that I'll look into this (many months ago) and as a side project I've examined many existing solutions as a source for ideas and I've also played around with various techniques I've came across in the past years (html5-web-stuff, features from the LMFDB website, etc.) It's not conclusive to me how it should be done, but I fully agree that the technical documentation is too technical and will never make users happy. A loose orientation around smaller topics with many examples is better, also a tight interlinking across all areas (some automatic, some manual) is key. What's also required are actual content contributors, that's why I've also focused to make it really easy to contribute (plaintext markdown with some extras, in the future this could also be ReST) So, if anyone wants to have a peek view what I've been playing around: http://collscientiae.github.io/ The main topics you can see are just for demo purpose and regarding Sage, I envision that there are 6 or more sage-specific top-level entries … and the one about Python might also be nice, but it's just one at the bottom. code: https://github.com/collscientiae -- Harald -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at http://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.
