Hi On Tue, Aug 26, 2008 at 8:07 PM, Harald Schilly <[EMAIL PROTECTED]> wrote: > > Hi, I want to propose a process to increase the quality of the Sage > documentation. This is the by far most annoying thing about Sage > according to the last survey. I think the userbase is already big and > willing enough to contribute more documentation. To do this in a more > coordinated way, there should be some sort of process and guidelines. >
I vote for it. And one very important thing IMHO is a script that could generate most of the code (images, sections, subsections, etc) from the worksheet. It is painful to have to manage two documents when correcting errors or changing the code of a cell. Maybe there should be two kind of cells : code and text(Latex or Html or structured) > I've seen a - in my eyes - very good approach at the netbeans.org > project. They organize and collect the documentation work in a > standard wiki system and maybe transform those articles or tutorials > into the official documentation later. They have a list of > contributions, a contact email address for each entry (feedback, > errors, and of course attribution! ...), a wish list, some status > information about ongoing processes, their own blog and their own > mailing list. I think, some or all of those ideas could work for Sage > as well and they are also compatible with possible paid contributors. > I started learning Java and Netbeans two months ago. It was not easy but the netbeans.org tutorials are definitely very helpful and encouraging. > Read more here > http://www.netbeans.org/community/articles/nb-communitydocs-200.html > docs: http://www.netbeans.org/community/commdocs.html > main organization page: http://wiki.netbeans.org/CommunityDocs > > I think, Sage could improve very much, by providing more documentation > towards explaining certain tasks, how they are accomplished (also > pointing out what *not* to do to avoid common pitfalls) or by > explaining basics more detailed. It is certainly not enough to point a > new user to an all-in-all documentation, because those documentations > require some knowledge about Sage in the first place, i.e. knowing > where to look for what. It is much more satisfying for new users to > present them thematically narrow examples to give them an instant > moment of success when they execute the tutorial on their own - and > then they are more encouraged to try more... > I am a mid level teacher/user and i confirm that Sage documentation is not *always* friendly. (but my respect to those who wrote it...) Narrow and exhaustive examples are very important i believe > Therefore, I hope, some folks are interested to start and once there > is already something online, more and more should come. > I am interested (in french ??) Philippe > ideas, thoughts, comments? H > > > > --~--~---------~--~----~------------~-------~--~----~ To post to this group, send email to sage-devel@googlegroups.com To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/sage-devel URLs: http://www.sagemath.org -~----------~----~----~----~------~----~------~--~---
