SG Instructions for Gridification Guide Contributions

From EGEE-see WIki

Jump to: navigation, search
[edit]

How to cover a topic

There is no strict structure for each particular topic or Wiki page. But there are two key factors to have in mind while preparing the guidelines:

  1. Put yourself in the position you were in when you started working in given area. Try to identify the instructions, hints and examples that you were missing and would help you the most at beginning and during later development. That is what you should write about. Now just write them for that imagined "former you".
  2. Try to transcend your particular application and describe the whole class of problems and solutions. Also try to make your examples usable for a wider audience and illustrative to those who are not familiar with your particular application. For example, a text on Web Authentication and Authorization with Gridsphere portal should include the usage of portlets, but notes on the parts of Gridsphere that could be used by Java web applications not based on portlets would be even more attractive. Similarly, a contribution on visualisation and distributed rendering could also describe an approach to generation of partial tasks and collection and integration of results, which is something that interests many developers...

If your topic or contribution is large, split it into several relatively independent or consecutively ordered Wiki pages. A good example for this is MPI (T9) section of the guide. Of course, at least one introductory paragraph at the beginning of each Wiki page should describe what the page is about.

Do not forget to check spelling and other possible errors of your contribution - they may end up in the project deliverable!

[edit]

General Recommendations

Here is also a small elaboration on recommendations from the Gridification Guide presentation at Thessaloniki PSC 05 Meeting:

  • Focus on your current commitments
    You may contribute to other areas as well, but first fulfill the obligations taken earlier. This is important for adequate coverage of topics.
  • If you contribute after December 1st, you may miss the D4.3 train
    D4.3 needs some time for integration and editing.
  • Keep sync with others, particularly with the topic leader
    There are several topics with announced contribution from may partners - Coordinate with others in order make the full coverage of the subject and avoid overlapping.
  • More collaboration on individual subjects is welcome!
    You can decide to cover just few sections in which you are most competent, and not to report on whole subject.
  • Review and improve others’ contributions
    The created Wiki pages should be freely updated and improved by developers who are not their initial creators. Wiki is about joint content generation, so read what others have written - perhaps your correction or small contribution can put the new light on the subject, or at least improve the quality of the text.
  • Things to avoid
    • Overlapping with others
      This both doubles the effort and lowers the quality of the text by producing overall redundancy - rather try to improve the contributions already provided by other authors.
    • Redundancy in your own contributions
      Repetitiveness would be tolerable in Wiki when covering particular trail in a single page. However, this looks bad in a printed document and should be avoided, since we want to convert this Wiki into a project deliverable. Repetitions can be avoided by better structuring of the text into alternate sections or by providing side-by side comparative descriptions and examples.
  • Provide original contributions outside of gLite User Guide
    • Introductory guides not present elsewhere
    • Examples and usage patterns
    • Hints, noticed problems, workarounds and solutions
    • Integration of otherwise scattered materials
    • Pointers to key resources and additional information
    Above are types of materials that can be provided within your contributions and are quite likely to provide some additional value. Simple duplication of material already present in other well-known resources is meaningless, not to mention possible authoring and copyright problems. But you can use other sources by proper citation within your original contribution.
[edit]

Basic Technicalities

The contributor must log on using a Wiki account obtained from the EGEE SEE ROC Wiki Sysops. Requests for Wiki accounts are handled via the SEEGRID help-desk (http://helpdesk.see-grid.org) creating a ticket and assigning it to the WIKI Task Manager Group.

Wiki markup is described at

If your original document is written using MS Word, you may find useful some of macros that are available at

There are also some recommendations to have in mind while writing contribution:

  • The first line of each contribution should point to the Gridification Guide with "This Wiki page is a part of [[SG Gridification Guide|SEE-GRID Gridification Guide]]." This will greatly improve the navigation and provide access to other related contributions - This is crucial for a user who finds the page using a search engine!
  • Each major contribution with a small number of contributors should have an introductory paragraph describing the participating institution(s). In wiki formatting, this could look like "This guide is contributed by [<URL> <Institution name>]." In a case that the contribution describes an original development, this should be specifically mentioned along with related project or application and their URLs.
  • When some external library, tool or framework is mentioned for the first time, it would be nice to provide a reference.
  • If a contribution is closely related to an application, it would be nice to title it like e.g. "<subject> case study". But if the most of the contribution is general, the application-specific part or example should be placed in a separate "Example" section.
  • If you want/expect some feedback on your contribution, please provide a contact e-mail within "Contact" section at the end of the contribution. This is particularly important if you are expecting some changes or comments, as editing of SEEGRID Wiki pages is allowed only to registered users.
Retrieved from "http://wiki.egee-see.org/index.php/SG_Instructions_for_Gridification_Guide_Contributions"
Personal tools