User:Abram/New User Guide Writing Guide

From Math Images
Jump to: navigation, search

Many of the items in the writing guide from the New User Guide are already covered elsewhere on other pages. In general, items about the content, writing, and layout of actual pages are covered in the checklist for writing good pages. Items that are about everything else (creating a user account, making sure your page doesn't already exist, etc.) are in the tour.

Items from the New User Guide writing guide that are not already somewhere else more logically belong grouped with other like items on a different page (see specific suggestions below).

For this reason, I think this section of the New User Guide can be gutted, with slight modification to other pages. See below for specific reasoning for each item.

  • Look through the help documents, especially the Wiki Tricks page so you know what resources this wiki has available to you.
All help documents that relate to writing can be linked to in the main help page. We can add a note to the beginning of each writing guide asking folks to check out the tour and the main help page.
  • Make sure you have made an account and log in to create a new math images page (you can edit existing pages without an account, but we recommend making an account if you are going to edit or write on this wiki).
This is in the tour, except that the tour should be corrected to say that having an account is helpful (right now, it says it's required).
  • We want our image pages to have an attractive image, together with descriptions of the math behind it that can be satisfying to users with many different levels of background. Start out with a very simple overview, likely hiding much of the more advanced material to keep from overwhelming readers (in particular going very light on equations). We've found it useful to keep the names of hidden subsections visible, serving as a come-on, but hiding the subsection contents (although maybe showing an intriguing image or so).
This is all covered in the checklist, except for the part about keeping hidden subsections visible (which will probably clear to anyone who peruses a couple of the S10 pages) and the part about showing an intriguing image (which is not always desirable, and the technical details involved in previewing images are a pain anyway).
  • In general use short paragraphs of just a couple sentences, and simple sentences. It's a real challenge to write clearly, simply, and still convey the mathematical concepts. Almost everyone needs to have their work read by others and to revise.
This is all covered in the checklist, except for the sentiment about needing revision, which is in the S11 page
  • For Math Image pages, or Helper Pages which double as math image pages, be sure to use the form, as described in the section above, to create or edit pages. For simpler Helper Pages, the form isn't necessary and just a simpler approach, using many of the tricks from the advanced user guide would suffice.
This is covered in the tour, except for the detail about Helper Pages, which can be easily added to the tour.
  • Search what pages already exist! There might already be some pages similar to the one you wanted to do, which could help you in making your page or give you related articles to link your page to. If a Math Image page already exists that is extremely similar to the one you were planning, perhaps you could merge your planned page and the already existing one (before such a large overhaul it would be considerate to plan it out with others in the discussion pages, however).
This makes sense to add to the tour.
  • Subsections within each section on the form should start out using a triple header, e.g. ===Subsection Name===
The sentiment about having a uniform approach to section headings I think will be self-evident to most people. The description of how to go about this technically belongs in Wiki Tricks.
  • Whenever a section of math can be particularly overbearing, at least at first glance, it might be wise to hide it (to learn about hiding sections, see the Wiki Tricks page) so that readers have time to read a little bit of background information before being loaded with equations.
This is covered in the checklist.
  • You can put other images in your page besides just the main one, in fact this is highly encouraged as long as they are relevant.
This is covered in the checklist.
  • For definitions that many users may already know, use a mouse-over balloon to explain it briefly, and perhaps have the mouse-over also serve as a link to any relevant Helper Pages. For more information on mouse-overs, see the Wiki Tricks page.
This is covered in the checklist.
  • If you don't understand some of the more sophisticated math for a page you are creating, you can leave a section blank and ask in the discussion and community portal for someone who does understand it to help you write it.
This is covered in the checklist.
  • Be sure to reference any resources you found especially useful in creating your page! At least two references is a good thing.
This is covered in the checklist, except that I can the bit about having two references.
  • Make sure you have the authority to publish the image you've chosen on this site! For more information, see our page on copyrights and the GNU Free Documentation License.
This can be added to the checklist.