From 8e2d2178483f47ca5e187bf332e182f1b4e35c8e Mon Sep 17 00:00:00 2001 From: "David W. Farmer" Date: Mon, 18 Mar 2019 10:01:04 -0400 Subject: [PATCH 1/4] Add guiding principles for the LMFDB --- README.md | 27 +++++++++++++++++++++++---- 1 file changed, 23 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 716e985643..2571fce9ea 100644 --- a/README.md +++ b/README.md @@ -15,10 +15,29 @@ Development * [Getting Started](https://github.com/LMFDB/lmfdb/blob/master/GettingStarted.md) -- cheat sheet for setting up lmfdb * [Development Guide](https://github.com/LMFDB/lmfdb/blob/master/Development.md) -- organizing development -Screenshot ----------- - -![LMFDB Screenshot](https://raw.github.com/wiki/LMFDB/lmfdb/lmfdb-screenshot-20120410.png) +The design of the LMFDB is guided by the following principles +------------------------------------------------------------- + +1. Each mathematical object has its own home page. Home pages +summarize basic invariants at the top, progressing to more advanced +information at the bottom. +2. Each home page lives at a mathematically meaningful, permanent URL. +3. Each mathematical object has a label which is mathematically +meaningful, and to the extent possible, human-readable and concise. +The translation between an object's label and its URL should be +relatively straightforward. +4. Each home page should list the names of the entities responsible +for producing the data on that page. +5. Each class of objects has a browse-and-search page, which has +browsing options in the upper portion of the page, and a search form +below. It should be possible to browse to the home page of an +object without having detailed knowledge about the underlying +mathematics. The search form should be (at least partially) visible +in a browser without scrolling the browse-and-search page. +6. Home pages and browse-and-search pages are developed through an +iterative process involving feedback from both experts and non-experts +in the subject, in order to ensure that the pages are useful to a +broad mathematical audience. [logo]: https://github.com/LMFDB/lmfdb/raw/master/lmfdb/static/images/lmfdb-logo.png "LMFDB" From 8f9b783671d82afc19ed9730367fda0beea98e76 Mon Sep 17 00:00:00 2001 From: Andrew Sutherland Date: Fri, 22 Mar 2019 01:29:57 -0400 Subject: [PATCH 2/4] Updates based on today's discussion As discussed in this afternoon's meeting, changed principles to guidelines and modified 6. I also amended 1 to mention knowls. --- README.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 2571fce9ea..575f94bc68 100644 --- a/README.md +++ b/README.md @@ -15,14 +15,14 @@ Development * [Getting Started](https://github.com/LMFDB/lmfdb/blob/master/GettingStarted.md) -- cheat sheet for setting up lmfdb * [Development Guide](https://github.com/LMFDB/lmfdb/blob/master/Development.md) -- organizing development -The design of the LMFDB is guided by the following principles -------------------------------------------------------------- +Guidelines +---------- -1. Each mathematical object has its own home page. Home pages +1. Each mathematical object should have its own home page. Home pages summarize basic invariants at the top, progressing to more advanced -information at the bottom. -2. Each home page lives at a mathematically meaningful, permanent URL. -3. Each mathematical object has a label which is mathematically +information at the bottom, with mathematical terms defined by knowls. +2. Each home page should have a mathematically meaningful, permanent URL. +3. Each mathematical object should be given a label that is mathematically meaningful, and to the extent possible, human-readable and concise. The translation between an object's label and its URL should be relatively straightforward. @@ -34,10 +34,9 @@ below. It should be possible to browse to the home page of an object without having detailed knowledge about the underlying mathematics. The search form should be (at least partially) visible in a browser without scrolling the browse-and-search page. -6. Home pages and browse-and-search pages are developed through an -iterative process involving feedback from both experts and non-experts -in the subject, in order to ensure that the pages are useful to a -broad mathematical audience. +6. Home pages and browse-and-search pages should address the needs +of both experts and non-experts in the subject, in order to ensure +that the pages are useful to a broad mathematical audience. [logo]: https://github.com/LMFDB/lmfdb/raw/master/lmfdb/static/images/lmfdb-logo.png "LMFDB" From 7021df7ddd267d81d0aea8357cf5d27f45f437f1 Mon Sep 17 00:00:00 2001 From: Andrew Sutherland Date: Fri, 22 Mar 2019 01:35:06 -0400 Subject: [PATCH 3/4] Added JC's suggested amendments to #1 Added mention of properties box, RCS knowls, and related objects to 1. --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 575f94bc68..a536afa9e8 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,10 @@ Guidelines 1. Each mathematical object should have its own home page. Home pages summarize basic invariants at the top, progressing to more advanced information at the bottom, with mathematical terms defined by knowls. +The right hand side of each home page should include a properties box +with key invariants including the liable, a "learn more about" box +with links to completeness, source, and reliability knowls, and when +applicable, a list of related objects. 2. Each home page should have a mathematically meaningful, permanent URL. 3. Each mathematical object should be given a label that is mathematically meaningful, and to the extent possible, human-readable and concise. From 312878e5efe8644ad3f57582ec45efea5fabe08a Mon Sep 17 00:00:00 2001 From: Andrew Sutherland Date: Fri, 22 Mar 2019 01:47:58 -0400 Subject: [PATCH 4/4] minor update to make 1 shorter --- README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index a536afa9e8..33a01eb7cb 100644 --- a/README.md +++ b/README.md @@ -22,9 +22,8 @@ Guidelines summarize basic invariants at the top, progressing to more advanced information at the bottom, with mathematical terms defined by knowls. The right hand side of each home page should include a properties box -with key invariants including the liable, a "learn more about" box -with links to completeness, source, and reliability knowls, and when -applicable, a list of related objects. +that summarizes key invariants, links to completeness, source, and +reliability knowls, and when applicable, a list of related objects. 2. Each home page should have a mathematically meaningful, permanent URL. 3. Each mathematical object should be given a label that is mathematically meaningful, and to the extent possible, human-readable and concise.