Skip to content

Latest commit

 

History

History
99 lines (60 loc) · 5.26 KB

Guidelines.md

File metadata and controls

99 lines (60 loc) · 5.26 KB
Raw

1. File system and naming conventions

  • 1.1. Enumerate every sub-folder in each given folder. The number should be a part of the name of each sub-folder, for instance "1_rigid_body", "1_setup". Don't use UPPER_CASE or Camel_Case

  • 1.2. Use minimal descriptive folder name in a given hierarchy of folders - e.g. "1_rigid_body/1_setup", not "1_tutorial_rigid_body/1_rigid_body_setup" - in this case "tutorial" is excessive in the first level, and "rigid_body" is redundant in the second level

  • 1.3. Use the all-lowercase-and-underscore file and folder names, for instance "1_rigid_body", not any of these: "1_Rigid_body", or "1_Rigid_Body", or "1_RIGID_BODY", or "1-rigid-body"

  • 1.4. Each tutorial (the Jupyter notebook and data files) should be placed in a separate folder so that any output generated by running the example is not mixed up with the output of other tutorials

  • 1.5. Every master tutorial (in each of these folders) should be named "tutorial.ipynb"

  • 1.6. Every final folder should include a "README.md" file describing the content of the corresponding folder and its content, potentially needed additional preparation/setup instructions

  • 1.7. Every final folder's "README.md" should have a link pointing to the top-level "README.md" (TOC)

  • 1.8. Section and subsection naming in the Tutorial files should use "Regular case", not the "ALL CAPS" nor the "Camel Case". The exceptions are the abbreviation, names, and punctuation rules.

2. Content

  • 2.1. All tutorials should contain all the necessary data (e.g. input files, etc.) for the user to be execute it without extensive additional setups, except for when other files are not allowed to be distributed according to their copyright.

  • 2.2. No reference to output of other tutorials, please. Each unit should be possible to run without running other units.

  • 2.3. No data files larger than 50 Mb are allowed (will not get to GitHub, per their restrictions)

3. Tutorial files

  • 3.1. Each tutorial file should contain a list (e.g. preferably a bullet-point list) of the learning objectives These are broad types of skills to learn, yet they should be formulated as a measurable objectives, e.g. Bad: "to learn molecular dynamics", good: "to setup and execute classical molecular dynamics with Libra's force fields"

  • 3.2. Each tutorial file should contain a list (e.g. preferably a bullet-point list) of the use cases These are general skills learned in this tutorial and should be formulated in a concise and easy-to-classify manner, for instance: "visualization of MOs", "classical MD", "preparing initial conditions". These terms should be common to those found in the "use cases" section of the master TOC (see 4.1). Each element of this list should have links to at least 1 place in the document illustrating this use case. Use anchors to add this navigation.

  • 3.3. Each tutorial file should contain a list (e.g. preferably a bullet-point list) of the functions learned These are the names of the Libra's functions or data classes that are used in this tutorial. The function names should be common to those found in the "functions learned" section of the master TOC (see 4.1). Each element of this list should have links to at least 1 place in the document illustrating the use of such a function. Use anchors to add this navigation.

  • 3.4. All Python imports should be done in the top of the document, not anywhere else

  • 3.5. Reduce the instructional redundancy - if possible, don't re-explain the material, if it is explained in other tutorials, simply provide a cross-link to those sections.

  • 3.6. Each tutorial file should be have a hierarchical structure of content - use the Markdown sections and sub-sections of any desired depth to organize the tutorials.

  • 3.7. The hierarchical structure of the tutorial should be summarized in a tutorial's TOC. The TOC should contain links to the corresponding sections of the tutorial for easy navigation.

  • 3.8. Each section of the tutorial should have a link bringing the viewer to the top of the tutorial.

4. The top-level README.md

  • 4.1. The top-level README.md shall contain the following items:

    • a) TOC with the link to all the tutorials
    • b) the list of the use cases (types of operations), whit the list of links to corresponding tutorials
    • c) the list of Libra functions (C++ and Python) and the links to the corresponding examples

5. Building the content

  • 5.1. If you are developing an advanced (or any other, really) tutorial and find the need for instruction on other topics that for instance you don't plan on explaining in the current tutorial, please open an "Issue" on GitHub. The opener of the "Issue" would then add a NEED TUTORIAL link with the actual link pointing to the "Issue" opened.

  • 5.2. In the "Issue opened", the opener needs to explan what functionality/data types should be covered.

  • 5.3. Once any of the existining "Issues" requesting the addition of new content is addressed, the opener of the "Issue" should be informed/notified. After than, the opener of the "Issue" add the references to the newly added material in place of the NEED TUTORIAL links added earlier.