On Monday, December 3, 2012 10:45:50 PM UTC+1, William wrote: > > If anybody reading this has any experience with how to dramatically > improve reference documentation of a big open source software project, > please share. >
Likely, there is nobody in the world. My take on this would be to start small and iterate. The thematic tutorials are nice, but would only fit into chapters and sub-chapters of some larger collection. Also, a strict hierarchical system won't work in my eyes, because a certain sub-topic should be accessible through different hierarchical paths. I could also envision some meta-tutorials, that explain what could be done for a certain problem (different ways of how a polynomial system can be solved, based on the ring and so on). Is it possible to organize documents in sphinx via tags or categories? Maybe we have to start to invent a utility script, that creates index and sub-index pages for sphinx, which collect and organize documents based on tags in them. The effect of this would be, that a novice user doesn't need to actively search through the functions (as they are in the sources), but could look at a list of high-level topics. Then, the sub-topics (with some description?) guide him/her to a specific tutorials. Clearly, this is just a rough idea and needs much more brainstorming :-) Harald -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To post to this group, send email to sage-devel@googlegroups.com. To unsubscribe from this group, send email to sage-devel+unsubscr...@googlegroups.com. Visit this group at http://groups.google.com/group/sage-devel?hl=en.
