Differences between revisions 9 and 46 (spanning 37 versions)

Sage Documentation Project

This is the main community website of the Sage Documentation Project. This page is used as a central point to organize the efforts to create new help pages, tutorials, examples and similar documentation efforts. To add a documentation page to this category, add a link to this page on the last line of the page. Click on "subscribe" above to be posted about changes.

Writing Great Documentation

Jacob Kaplan-Moss has written a series of three articles on how to write great documentation for any open source project. Here is a list of his articles:

What to write --- Various types of documents that a project should have, including reference manual, tutorials, brief feature tours, development guidelines, etc.
Technical style --- good technical styles to follow.
You need an editor -- on the importance of having an editor to look after the project's documentation.

Darrell Anderson has some tips on technical writing that are well worth a read:

Bigshot Words --- some words to avoid. Dilbert also has some tips.
A Proofreader’s Checklist --- common grammatical and spelling mistakes to look out for.
Technical Writing Tips --- numerous points to keep in mind in technical writing.

Other issues

It also helps to use a spell checker.
Documentation issues in open source from OSS Watch.
How to Write Documentation that Will Lead to New Users by Jack Herrington.
Open-source documentation: in search of user-driven, just-in-time writing by Erik Berglund and Michael Priestley. In "SIGDOC '01: Proceedings of the 19th Annual International Conference on Computer Documentation", ACM, pages 132--141, 2001.
Documentation by [insert doc type] covers what isn't documentation.

Published Documents

Pages in this wiki (should belong to the category "DocumentationProject").

Title/URL	lang	Abstract	Author	Released/Updated
Netbeans	en	help for coding Python/Sage with Netbeans GUI	[email protected]	2009-01-18/-
WubiGuide	en	Newbie Wubi Linux Sage install under Windows	[email protected]	2009-05-17

External Documents

Not in this wiki (i.e. PDF or website).

Title/URL	lang	Abstract	Author	Released/Updated
Sage and Cython: A Brief Introduction html	en	This is a quick introduction to Sage,[...] One thing I will highlight is using Cython in Sage to make very fast code in an easy way.	Marshall Hampton	-/2008-05-09
Number Theory and the RSA Public Key Cryptosystem pdf	en	This tutorial uses Sage to study elementary number theory and the RSA public key cryptosystem. A number of Sage commands will be introduced that help us to perform basic number theoretic operations such as greatest common divisor and Euler’s phi function. We then introduce the RSA cryptosystem and use Sage’s built-in commands to encrypt and decrypt data via the RSA algorithm.	Minh Van Nguyen	2008-11-04/2009-07-25
Linear error-correcting codes pdf	en	This tutorial introduces some of Sage's functionality in the theory of error-correcting codes.	David Joyner and Robert Miller	2008-05
Group Theory and SAGE: A Primer pdf sws tex	en	This is a compilation of Sage commands useful for a student studying group theory for the first time. The SAGE worksheet version has executable cells.	Rob Beezer	2008-11-05/2009-01-30
ImageJ in a Sage notebook, an example of Python calling Java	en	This blogpost explains how to call Java programs from Sage via Jpype Python module	Frédéric Morain-Nicolier	2009-11-10
Sage in practice at Mendelu link	en/cz	Sage html refcard (en) and worksheets from lectures (en/cz)	Robert Marik	2009-12

Documents in the Work

Title/Url	lang	Author	Progress/Status/Need Help
Sage Wikibook Project	en	-	open for anyone

Wish List

This is a list of requested documentations.

Type	Priority	lang	Purpose and Direction
HowTo	high	en	Setup Sage in a classroom situation as a central server.
Examples	medium	en	Plotting of functions, examples how various kinds of functions can be plotted, explain parameters
Numbertypes and Conversation	high	en	Write a guide explaining the different types of numbers in Sage. What are they for (examples), how to convert, which modules are available (e.g. how works Sage->Python->Mpmath ?) and so on. Should target new Sage users, especially if they are used to simpler environments without different number types. Should be part of "Tutorial"

Types

Some definitions on what is what in the list above. (If someone has better definitions, please edit!)

Howto: Basic step-by-step guide with screenshots, easy to use, straightforward, probably often updated.
Tutorial: Explain a topic, how to do something, similar to howto...
Guide: More general than howto and tutorial. For example, explain background knowledge and connect the dots.
Examples: List examples on a particular topic. The levels "beginner", "advanced" and "pro" can be used to indicate the level of prior knowledge, where "pro" involves knowledge about programming with Sage, i.e. also Python, while "advanced" only requires an understanding of Sage's basic functionalities and an implicit knowledge about Python programming.
Teaching: Material used in teaching.

Documents by Category

DocumentationProject

-  ⇤ ← Revision 9 as of 2008-09-01 09:11:48 → 
  Size: 2099
  Editor: schilly
  Comment:
+   ← Revision 46 as of 2010-01-20 08:57:56 → ⇥
  Size: 7159
  Editor: Minh Nguyen
  Comment: consistent separation between sections
-Deletions are marked like this.
+Additions are marked like this.
 Line 5:
-Line 6:
+Line 7:
-This is the main community website of the '''Sage Documentation Project''' This page is used as a central point to organize the effords to create new help pages, tutorials, examples and similar. To add a documentation page to this category, add a link to this page on the last line of the page. Click on "subscribe" above to be posted about changes.
+This is the main community website of the '''Sage Documentation Project'''. This page is used as a central point to organize the efforts to create new help pages, tutorials, examples and similar documentation efforts. To add a documentation page to this category, add a link to this page on the last line of the page. Click on "subscribe" above to be posted about changes.


== Writing Great Documentation ==

Jacob Kaplan-Moss has written a series of three articles on how to write great documentation for any open source project. Here is a list of his articles:

 1. [[http://jacobian.org/writing/great-documentation/what-to-write/|What to write]] --- Various types of documents that a project should have, including reference manual, tutorials, brief feature tours, development guidelines, etc.

 1. [[http://jacobian.org/writing/great-documentation/technical-style/|Technical style]] --- good technical styles to follow.

 1. [[http://jacobian.org/writing/great-documentation/editors/|You need an editor]] -- on the importance of having an editor to look after the project's documentation.

Darrell Anderson has some tips on technical writing that are well worth a read:

 1. [[http://humanreadable.nfshost.com/howtos/bigshot_words.htm|Bigshot Words]] --- some words to avoid. [[http://www.dilbert.com/strips/comic/1992-12-21|Dilbert]] also has some tips.

 1. [[http://humanreadable.nfshost.com/howtos/proofreader.htm|A Proofreader’s Checklist]] --- common grammatical and spelling mistakes to look out for.

 1. [[http://humanreadable.nfshost.com/howtos/technical_writing_tips.htm|Technical Writing Tips]] --- numerous points to keep in mind in technical writing.


=== Other issues ===

 1. It also helps to use a spell checker.
 1. [[http://www.oss-watch.ac.uk/resources/documentation.xml|Documentation issues in open source]] from OSS Watch.
 1. [[http://www.devx.com/devx/Article/11839/0/page/2|How to Write Documentation that Will Lead to New Users]] by Jack Herrington.
 1. [[http://portal.acm.org/citation.cfm?id=501543|Open-source documentation: in search of user-driven, just-in-time writing]] by Erik Berglund and Michael Priestley. In "SIGDOC '01: Proceedings of the 19th Annual International Conference on Computer Documentation", ACM, pages 132--141, 2001.
 1. [[http://www.grillbar.org/wordpress/?p=264|Documentation by [insert doc type]]] covers what isn't documentation.
-Line 9:
+Line 39:
+Pages in this wiki (should belong to the category "DocumentationProject").
|| '''Title/URL''' || '''lang''' || '''Abstract''' || '''Author''' || '''Released/Updated''' ||
|| [[Netbeans]] || en || help for coding Python/Sage with Netbeans GUI || [email protected] || 2009-01-18/- ||
|| WubiGuide || en || Newbie Wubi Linux Sage install under Windows || [email protected] || 2009-05-17 ||
-Line 10:
+Line 44:
-|| '''Title/URL''' || '''lang''' || '''Author''' || '''Released/Updated''' ||
|| empty (link to wiki page) || en  || [email protected] ||  release date/update date ||
-Line 13:
+Line 45:
-=== External Documents ===
|| '''Title/URL''' || '''lang''' || '''Author''' || '''Released/Updated''' ||
|| [http://openwetware.org/wiki/Open_writing_projects/Sage_and_cython_a_brief_introduction Sage and Cython: A Brief Introduction] || en || Marshall Hampton || -/2008-05-09 ||
+== External Documents ==

Not in this wiki (i.e. PDF or website).
|| '''Title/URL''' || '''lang''' || '''Abstract''' || '''Author''' || '''Released/Updated''' ||
|| Sage and Cython: A Brief Introduction [[http://openwetware.org/wiki/Open_writing_projects/Sage_and_cython_a_brief_introduction|html]] || en || This is a quick introduction to Sage,[...] One thing I will highlight is using Cython in Sage to make very fast code in an easy way. || Marshall Hampton || -/2008-05-09 ||
|| Number Theory and the RSA Public Key Cryptosystem [[http://nguyenminh2.googlepages.com/sage_numtheory-rsa.pdf|pdf]] || en || This tutorial uses Sage to study elementary number theory and the RSA public key cryptosystem. A number of Sage commands will be introduced that help us to perform basic number theoretic operations such as greatest common divisor and Euler’s phi function. We then introduce the RSA cryptosystem and use Sage’s built-in commands to encrypt and decrypt data via the RSA algorithm. || Minh Van Nguyen || 2008-11-04/2009-07-25 ||
|| Linear error-correcting codes [[http://sage.math.washington.edu/home/wdj/cookbook/coding-theory/sage-coding-cookbook.pdf|pdf]] || en || This tutorial introduces some of Sage's functionality in the theory of error-correcting codes. || David Joyner and Robert Miller || 2008-05 ||
|| Group Theory and SAGE: A Primer [[http://buzzard.ups.edu/sage/sage-group-theory-primer.pdf|pdf]] [[http://buzzard.ups.edu/sage/sage-group-theory-primer.sws|sws]][[http://buzzard.ups.edu/sage/sage-group-theory-primer.tex|tex]] || en ||This is a compilation of Sage commands useful for a student studying group theory for the first time. The SAGE worksheet version has executable cells. ||Rob Beezer ||2008-11-05/2009-01-30 ||
|| [[http://pixel-shaker.fr/en/2009/11/utiliser-imagej-dans-un-notebook-sage-un-exemple-dappel-de-java-depuis-python/|ImageJ in a Sage notebook, an example of Python calling Java]] || en || This blogpost explains how to call Java programs from Sage via Jpype Python module || Frédéric Morain-Nicolier || 2009-11-10 ||
|| Sage in practice at Mendelu [[http://user.mendelu.cz/marik/sage/|link]] || en/cz || Sage html refcard (en) and worksheets from lectures (en/cz) || Robert Marik || 2009-12 ||
-Line 20:
+Line 60:
-|| pageUrl   || es   || mail  || 0% ||
+|| [[http://en.wikibooks.org/wiki/Sage_(Mathematical_Software)|Sage Wikibook Project]] || en || - || open for anyone ||
-Line 23:
+Line 64:
-Line 24:
+Line 66:
+|| '''Type''' || '''Priority''' || '''lang''' || '''Purpose and Direction''' ||
|| !HowTo || high || en || Setup Sage in a classroom situation as a central server. ||
|| Examples || medium || en || Plotting of functions, examples how various kinds of functions can be plotted, explain parameters ||
|| Numbertypes and Conversation || high || en || Write a guide explaining the different types of numbers in Sage. What are they for (examples), how to convert, which modules are available (e.g. how works Sage->Python->Mpmath ?) and so on. Should target new Sage users, especially if they are used to simpler environments without different number types. Should be part of "''Tutorial''" ||
-Line 25:
+Line 71:
-|| '''Type''' || '''Priority''' || '''lang''' || '''Purpose and Direction''' ||
|| !HowTo || high  || en   || Setup Sage in a classroom situation as a central server. ||
|| Examples || medium || en || Plotting of functions, examples how various kinds of functions can be plotted, explain parameters ||
-Line 29:
+Line 72:
-'''Types'''
 * Howto: Step-by-Step guide with screenshots, easy to use, straightforward, probably often to update.
 * Guide: more general than howto, for example, explain background and connect the dots.
 * Examples: List examples on a particular topic, level "beginner", "advanced" and "pro" indicate the level of prior knowledge, where "pro" involves knowledge about programming with Sage, i.e. also Python, while "advanced" does only require to understand the basics of Sage and an implicit knowledge about Python programming.
+== Types ==

Some definitions on what is what in the list above. (If someone has better definitions, please edit!)

 * ''Howto'': Basic step-by-step guide with screenshots, easy to use, straightforward, probably often updated.
 * ''Tutorial'': Explain a topic, how to do something, similar to howto...
 * ''Guide'': More general than howto and tutorial. For example, explain background knowledge and connect the dots.
 * ''Examples'': List examples on a particular topic. The levels "beginner", "advanced" and "pro" can be used to indicate the level of prior knowledge, where "pro" involves knowledge about programming with Sage, i.e. also Python, while "advanced" only requires an understanding of Sage's basic functionalities and an implicit knowledge about Python programming.
 * ''Teaching'': Material used in teaching.
-Line 35:
+Line 84:
-[[FullSearch()]]
+<<FullSearch>>
-Line 38:
+Line 88:
- DocumentationProject
+ . DocumentationProject

Diff for "DocumentationProject"