You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+61-39Lines changed: 61 additions & 39 deletions
Original file line number
Diff line number
Diff line change
@@ -28,42 +28,64 @@ Plan: move into production at https://ideas-productivity.org/ in November 2023
28
28
29
29
*Note: for events, see `_events/README.md` (to be added)*
30
30
31
-
* General
32
-
* This site represents the entire IDEAS family of projects and spin-offs. All content should reflect this (e.g., connections are encouraged, writing as if the project or activity is completely separate from anything else is discouraged).
33
-
* We prefer shorter "light-read" content to longer content and more formal language. The website is not a technical paper -- pasting content from a paper is probably not desirable.
34
-
* Longer-form content is okay if this is the only place that it appears. Consider shorter content that links to outside resources. Longer-form content is more likely to appear further down the website hierarchy (for example on a sub-page of an activity rather than the activity's main page)
35
-
* Try to avoid significant content on a topic appearing in multiple places on the site. If there is a page with the "meat" of the topic, other mentions can be shorter and point to the meat
36
-
* Cross-linking within the site is encouraged
37
-
* External links are encouraged, but we have a strong preference for persistent identifiers (e.g., DOI links) and links that we expect to be durable
38
-
* Language and styling
39
-
* We prefer to use standard Markdown markup over HTML unless there is a particular reason
40
-
* Page titles and other `title` content should use title case
41
-
* Other headings should use sentence case
42
-
* We prefer to use H1 as the highest level headings for page content (not H2)
43
-
* For most cases, we would expect a page to utilize at most two levels of headings -- if you need H3s ask yourself if you're going into too much detail
44
-
*`blurbs` (an optional element of most pages and include files) used more or less as subtitles should use sentence case but should *not* end with periods
45
-
* Subtitle `blurbs` should active "-ing" words where possible
46
-
* Use subtitle `blurbs` only where they make sense -- they're *optional*
47
-
*`blurbs` for `text-biglink.html` includes should be all lowercase, except for acronyms or key phrases
48
-
* For link blurbs, we prefer the language "learn more about..." over something simpler, like "visit..."
49
-
* For project names that start with "IDEAS", use a hyphen to link to a distinguishing term. For example, IDEAS-Classic, IDEAS-ECP, or IDEAS-Watersheds rather than IDEAS Classic, IDEAS ECP, or IDEAS Watersheds
50
-
* Graphics
51
-
* Graphics with a transparent background are generally preferred wherever possible. This means PNG or GIF format. JPEG files do not support transparent backgrounds
52
-
* The use of (technically appropriate) "eye-candy" images is encouraged to enhance visual interest
53
-
* Be sure to credit image sources where appropriate
54
-
* Content-specific
55
-
* main nav bar (across the top) (`_data/nav-config.yml`)
56
-
* To level navbar labels should be all lowercase
57
-
* Menu items in dropdown should be title case
58
-
* Main page
59
-
* Overview
60
-
* Activities
61
-
* Activities are something substantial which would be recognized by the public. Funded projects, obviously, but also activities launched by a funded project that may have developed an independent identity with the public. Events, even an organized series of events, fall under Resources rather than Activities.
62
-
* We currently categorize Activities as *current*, *spin offs*, and *past*. Spin offs may be separate projects that were actually spun out of another project in the IDEAS umbrella (e.g., xSDK) or activities which are still run by an IDEAS project but have a strong independent identity. This can be a bit of a judgement call, so discuss it with others if you have any questions
63
-
* Activities that have a separate web presence will generally have a single summary page here with a `text-biglink.html` link to the outside presence at the bottom
64
-
* Activities for which this is the only web presence are encouraged to provide more extensive content (e.g., IDEAS-Classic)
65
-
* For *past* activities, we should consistently indicate the years during which the project was active, to help put it in context
66
-
* For the main page for the activity, start the body of the page with a sentence like "*This project was active 2014–2017.*" (note the use of italics). See [IDEAS-Classic](https://ideas-productivity.github.io/activities/ideas-classic/) as an example
67
-
* On the cards for past activities, put the dates in the `title` field, like "IDEAS-Classic (2014-2017)". See the IDEAS-Classic card at the bottom of the [Activities](https://ideas-productivity.github.io/activities/) page as an example
68
-
* Resources
69
-
* Join
31
+
### General
32
+
33
+
* This site represents the entire IDEAS family of projects and spin-offs. All content should reflect this (e.g., connections are encouraged, writing as if the project or activity is completely separate from anything else is discouraged).
34
+
* We prefer shorter "light-read" content to longer content and more formal language. The website is not a technical paper -- pasting content from a paper is probably not desirable.
35
+
* Longer-form content is okay if this is the only place that it appears. Consider shorter content that links to outside resources. Longer-form content is more likely to appear further down the website hierarchy (for example on a sub-page of an activity rather than the activity's main page)
36
+
* Try to avoid significant content on a topic appearing in multiple places on the site. If there is a page with the "meat" of the topic, other mentions can be shorter and point to the meat
37
+
* Cross-linking within the site is encouraged
38
+
* External links are encouraged, but we have a strong preference for persistent identifiers (e.g., DOI links) and links that we expect to be durable
39
+
40
+
### Language and styling
41
+
42
+
* We prefer to use standard Markdown markup over HTML unless there is a particular reason
43
+
* Page titles and other `title` content should use title case
44
+
* Other headings should use sentence case
45
+
* We prefer to use H1 as the highest level headings for page content (not H2)
46
+
* For most cases, we would expect a page to utilize at most two levels of headings -- if you need H3s ask yourself if you're going into too much detail
47
+
*`blurbs` (an optional element of most pages and include files) used more or less as subtitles should use sentence case but should *not* end with periods
48
+
* Subtitle `blurbs` should active "-ing" words where possible
49
+
* Use subtitle `blurbs` only where they make sense -- they're *optional*
50
+
*`blurbs` for `text-biglink.html` includes should be all lowercase, except for acronyms or key phrases
51
+
* For link blurbs, we prefer the language "learn more about..." over something simpler, like "visit..."
52
+
* For project names that start with "IDEAS", use a hyphen to link to a distinguishing term. For example, IDEAS-Classic, IDEAS-ECP, or IDEAS-Watersheds rather than IDEAS Classic, IDEAS ECP, or IDEAS Watersheds
53
+
54
+
### Graphics
55
+
56
+
* Graphics with a transparent background are generally preferred wherever possible. This means PNG or GIF format. JPEG files do not support transparent backgrounds
57
+
* The use of (technically appropriate) "eye-candy" images is encouraged to enhance visual interest
58
+
* Be sure to credit image sources where appropriate
59
+
60
+
### Content-specific
61
+
62
+
* main nav bar (across the top) (`_data/nav-config.yml`)
63
+
* To level navbar labels should be all lowercase
64
+
* Menu items in dropdown should be title case
65
+
* Main page
66
+
* Overview
67
+
* Activities
68
+
* Activities are something substantial that would be recognized by the public. Funded projects, obviously, but also activities launched by a funded project that may have developed an independent identity with the public. Events, even an organized series of events, fall under Resources rather than Activities.
69
+
* We currently categorize Activities as _current_, spin-offs, and *past*. Spin-offs may be separate projects that were actually spun out of another project in the IDEAS umbrella (e.g., xSDK) or activities that are still run by an IDEAS project but have a strong independent identity. This can be a bit of a judgment call, so discuss it with others if you have any questions
70
+
* Activities that have a separate web presence will generally have a single summary page here with a `text-biglink.html` link to the outside presence at the bottom
71
+
* Activities for which this is the only web presence are encouraged to provide more extensive content (e.g., IDEAS-Classic)
72
+
* For *past* activities, we should consistently indicate the years during which the project was active, to help put it in context
73
+
* For the main page for the activity, start the body of the page with a sentence like "*This project was active 2014–2017.*" (note the use of italics). See [IDEAS-Classic](https://ideas-productivity.github.io/activities/ideas-classic/) as an example
74
+
* On the cards for past activities, put the dates in the `title` field, like "IDEAS-Classic (2014-2017)". See the IDEAS-Classic card at the bottom of the [Activities](https://ideas-productivity.github.io/activities/) page as an example
75
+
* Resources
76
+
* Join
77
+
78
+
#### Team pages
79
+
80
+
"Team pages" typically include a list of members of the project team, their affiliations, project roles, and perhaps additional information. Former team members are often recognized as "Alumni" and listed without photos. Examples include the [IDEAS-Classic team page](/activities/ideas-classic/team) and the [IDEAS-ECP team page](/activities/ideas-ecp/team).
81
+
82
+
* Use the `list-6x.html` include file for a photo gallery. This provides a 6-column display. Multiple includes can be used to handle more than 6 people.
83
+
* Use the `list_-x.htm` include file for a text-only list. This provides a 3-column display. Multiple includes can used to handle more than 3 people.
84
+
* The `group-title` and optionally `group-blurb` arguments should be used on the *first* include in a group to provide the heading and optionally a brief description. Subsequent includes in the block should not use any of the `group-*` arguments.
85
+
* Participant names and short affiliations (e.g., "Firstname Lastname (XNL)") should appear as the `title*` arguments to the include.
86
+
* Information about project roles (e.g., "Institutional PI" or "Computing Facility Liaison") can be included using the `blurb*` arguments. These should be succinct and should be in plain text (not bold or italicized).
87
+
* Either kind of listing (`list-6x` or `list-3x`) can be automated, listing the relevant information in the YAML metadata and processing it in the body using Jekyll (Liquid) scripting. See the [IDEAS-ECP team page](/activities/ideas-ecp/team) for an example (and code to copy).
88
+
* For the page `title``, simply using "Team" is preferred
89
+
* It may be appropriate to include a `blurb` (subtitle) that briefly summarizes the institutional membership of the project team (e.g,, "The IDEAS-Classic team includes members from seven national laboratories, one university, and five DOE computing facilities"). As per the guidelines above, blurbs should *not* end with a period.
90
+
* In choosing headings for the various blocks, be sensitive to the repetition of words. If you're on the "Team" page, try to avoid repeating the word "Team" in every heading. Likewise, if it is clear that this is the IDEAS-ECP team page (perhaps through the page subtitle or other indications), the project name probably doesn't need to be repeated in the headings.
91
+
* If you're listing the institutional affiliations of each participant, you don't really need a section that calls out all of the participating institutions. This might be more appropriate for an "Overview" page for the project (i.e., the parent of the Team page).
0 commit comments