[gimp-web-devel/pat/bootstrap] content: improve the website contribution page.

From: Jehan <jehanp src gnome org>
To: commits-list gnome org
Cc:
Subject: [gimp-web-devel/pat/bootstrap] content: improve the website contribution page.
Date: Tue, 13 Sep 2022 19:19:16 +0000 (UTC)
commit 7c6b3ebe693b61b8e9737c2c8b4dbf671f37fd93
Author: Jehan <jehan girinstud io>
Date:   Tue Sep 13 21:15:27 2022 +0200

    content: improve the website contribution page.
    
    Even though the original contents looked very outdated, a lot could be
    salvaged. Simply I transformed many of the "plans" into "concepts" and
    "principles".
    I also moved around and reorganized the page contents.

 content/core/WGO/_index.md | 315 ++++++++++++++++++++++++++++-----------------
 1 file changed, 200 insertions(+), 115 deletions(-)
---
diff --git a/content/core/WGO/_index.md b/content/core/WGO/_index.md
index 0122504..3ebdf9b 100644
--- a/content/core/WGO/_index.md
+++ b/content/core/WGO/_index.md
@@ -1,64 +1,76 @@
 ---
-title: "Contributing to the main website (www.gimp.org)"
+title: "Contributing to the main website: www.gimp.org"
 Author: "GIMP team"
 Date: 2016-10-25
+toc: true
 ---
 
-## Why?
-
-The email from Cristobal on the Gimp-web list recently prompted this further discussion.
-His summary of work and ideas were documented on [this page](https://leivaburto.github.io/gimp-web-revamp/).
-
-### Assumptions
-
-* We (the royal 'We') could benefit from having more content on WGO, in particular tutorials.
-* Lowering the barrier-to-entry can help entice users to generate new content.
-* A new facelift can't hurt from a PR standpoint.
-
-### Benefits
-
-There are a few possible benefits from conducting a redesign now:
-
-* Better organization of content
-:If the content organization is approached as described below.
-
-* Modern Look
-* A chance to consider usability and ease of access for users (and to improve it)
-* Lowering the barrier to entry for new contributors/contributions.
-* Responsive Design
-
-## Summary
-
-From an architecture standpoint, the general idea is to separate content from presentation.
-This is already how the current site exists, though the implementation is a little clunky.
-
-* Possibly having role-based permissions against different areas of a git repository (admin, presentation, 
content, tutorials, news, etc...) ([git sub-modules](http://www.git-scm.com/book/en/v2/Git-Tools-Submodules) 
were mentioned as a way to manage this).
-* The proposed idea is to separate WGO content into more user-friendly discrete pieces, such as individual 
[Markdown](http://daringfireball.net/projects/markdown/) text files.
-* These text files (+assets) would then be passed through a processor to be turned into static HTML assets.
-* These static HTML assets would then be served to users.
-
-Overall, the approach from Cristobal considers the problem one of creating 
'''Application'''/'''Content'''/'''Presentation''' layers.
-
-## Application - Role based access (git submodules)
-
-There was originally proposed utilizing [Git 
submodules](http://www.git-scm.com/book/en/v2/Git-Tools-Submodules) as a means for segregating 
content/admin/presentation from each other within a repository.
-
-I (PatDavid) am not familiar enough with Git to speak to this, and could at some point use some input on the 
idea.
-As near as I can tell, the idea is that sub-folders of a Git project can be designated as sub-modules from 
other projects?
-
-It appears that this may be something that can be separately addressed later in the process of implementing 
a new site.
-
-## Content
-
-The content for the website can be decoupled from the presentation layer.
+GIMP community does not only need developers. We welcome all sorts of
+contributions: design, testing, bug triaging, translators… and of course
+website improvements!
+
+Even the website you are reading right now can be [contributed
+to](/about/), for instance to propose new developer tutorials or
+improving existing ones.
+
+This page is about the [main website](https://www.gimp.org/), often
+abbreviated <abbr title="Www.Gimp.Org">WGO</abbr>, which is the central
+point to get information about GIMP.
+
+## Possible improvements
+
+Some of the many things which were cited across the years are:
+
+* Porting the website to Hugo (work started by Patrick David). We
+  already lowered the barrier-to-entry when [moving to Pelican in
+  2015](https://www.gimp.org/news/2015/11/22/20-years-of-gimp-release-of-gimp-2816/#new-website)
+  and believe the website is due for a new facelift. It could help
+  entice users to generate new content.
+* More tutorials on WGO for specific useful workflows.
+* Add some community news: events organized by community members, better
+  advertizing the events that the core team itself organizes…
+* Add nice "behind the scene news": interviews, meeting users…
+* More contents updates in general: more book listings, nice images,
+  tutorials, news…
+
+## Base website principles
+### Static content
+
+As all GIMP websites, WGO is static-only, or to be more accurate
+server-side static. Indeed we don't use any server-side dynamic language
+such as PHP or Python; our web server only serves pre-built HTML, CSS
+and Javascript files. This has the following advantages:
+
+* The website is much faster as our web server hosts and directly serves
+  existing files. No on-the-fly compilation (or cache system), no
+  database, no interpreter running.
+* The website is much safer. We can't have any SQL injection (or any
+  kind of code injection), private data leaking (nothing is private on
+  our website).
+* Our website is saner and doesn't require GDPR handling or cookie
+  warnings: we don't gather anyone's private data, nor do we want
+  to. There is simply nothing to warn about with a static website.
+
+The only dynamic part of the website can be for Javascript, which we
+keep to a minimum. In particular, **a very important rule is that the
+website should perfectly work without Javascript!**
+For instance, we use JavaScript to redirect to a "thank you" page with
+some info and links after the "Download" button was clicked. With JS
+disabled, the download button would still work (only the redirection
+would not happen, that's all).
+
+### Simple content format and separated from style
+
+The content for the website is decoupled from the presentation layer.
 One method of doing this is to house all of the content in an easy-to-use plain text format such as Markdown 
(or some combination of Markdown + html).
 
 A benefit of separating the content from the presentation layer is portability of the content.
 It becomes easier later on to re-adapt the content layer to a new presentation layer as needed.
 This also helps to lower the barrier to entry, as any given piece of content is a self-contained folder of 
plain-text markdown (or html), as well as the associated assets needed.
-This is already similar to what is being done on WGO, but even further removing the presentation information 
as well.
 
-Consider, for example, this snippet from the tutorial "GIMP Quickies":
+This was already the case on WGO before 2015, then it got even further removing the presentation information 
as well in the Pelican port. The upcoming Hugo port will simplify even further.
+
+Consider, for example, this historical snippet from the tutorial "GIMP Quickies":
 
 ```html
 <!--#include virtual="/includes/wgo-xhtml-init.xhtml" -->
@@ -118,102 +130,175 @@ For quick access, these are the four main points I’ll cover in this quick tuto
 * [or Flip an Image](Rotate)(#transform)
 ```
 
-## Presentation
+### Important website features
 
-With the content abstracted further to plain text files, the presentation data for WGO can be managed 
separately from the content.
-This allows not only parallel workflows but the possibility of drastic modification to the presentation 
layer without any undue burden on the content creators.
+Here are a list of things that are the most important to users visiting
+the page (as per original discussion between Schumaml and Patdavid
+during the Pelican redesign):
 
-The presentation layer is also something that is usually defined in terms of the static site generation (but 
can be modified/customized as needed).
+* The project name. Main branding: GIMP - The GNU Image Manipulation Program
+* How do I get it (Download)?
+* What is it (The Free &amp; Open Source Image Editor)?
+* How do I use it (tutorials/docs)?
+* News
+* Get Involved
+* Donate
 
-For pixls.us, I had used a bit of Adam Kaplan's [Grid](http://adamkaplan.me/grid/) as a basis for extending 
the site.
-This has the benefit of being a responsive design with various possible screen sizes accounted for in @media 
CSS.
-This is not a requirement, of course, but if doing a redesign we might as well consider responsive and 
mobile-first options.
+Heare are the ideas Patdavid proposed moving forward with:
 
-## Requirements
+* The main page should serve these distinct purposes (*roughly in order of importance*):
+  * Clearly state the name of the project
+  * Clearly state the description of the project
+  * Clearly provide a means for getting the software
+  * Display recent news items/articles/blog posts
+  * Describe the program in high-level
+
+  Basically, anyone landing on the main page should have no doubt what they are looking at, what the program 
is for, and how to get it.
+* Try to keep the existing URL structure intact as much as possible.
+  * The only way it might not be the same going forward could be due to removal of some pages that could be 
considered extraneous.
+  * Even then, the pages should probably still exist to not break anything (just soft-remove them by no 
longer linking to them from anywhere).
+* Consolidate page information onto a single page as appropriate.
+  For example *Screenshots* and *Features* might be better off having their information be 
presented/duplicated onto the main page.
+
+These concepts are still true to this day.
 
-### Current Site
+## Current website organization
 
-A look at the current site and types of pages that a redesign would need to support.
-Looking at the WGO right now shows a very simple breakdown of content type into two main types:
+Looking at WGO right now shows a very simple breakdown of content type into two main types:
 
-# News Entry
-# Static Pages
+* News Entry
+* Static Pages
 
 These are the primary page types we can find.
 
-#### News Entry/Article Post
+### News Entry/Article Post
+
+News entries are relatively simple, as they've primarily been the
+snippets of updates shown in reverse chronology order on the [landing
+page of WGO](http://www.gimp.org/).
 
-News entries are relatively simple, as they've primarily been the snippets of updates shown in reverse 
chron. order on the [main WGO](http://www.gimp.org/) page.
+For years, there have been talks to sub-categorize these a bit, in
+particular with:
 
-#### Static Pages
+* Core team events: we already announce events such as Libre Graphics
+  Meeting or other [team meetups](/conferences/) but not always as well
+  as we could. A "Future event" section could also be interesting as a
+  calendar where people can check upcoming events in their area.
+* Community events: we could/should encourage the broader community to
+  post about their own events involving GIMP.
+* Community-building: apart from release news and events, it would be
+  awesome to get community-building articles, such as interviews (e.g.
+  the interview of 
[mitch](https://www.gimp.org/news/2017/03/01/an-interview-with-michael-natterer-gimp-maintainer/)
+  and of 
[schumaml](https://www.gimp.org/news/2017/05/15/an-interview-with-michael-schumacher-gimp-administrator/)
+  written a few years back by Jehan. Other than contributors interviews,
+  we could have GIMP users interviews (the ones doing really great stuff
+  with GIMP or working professionally in particular).
 
-The rest of the pages can be considered simple static pages.  These include:
+### Static Pages
+
+The rest of the pages can be considered simple static pages. These include:
 
-* Screenshots
 * Features
+* Release Notes
 * Downloads
 * Documentation
-  * User Manual (''see below'')
+  * User Manual (*see below*)
   * Tutorials
   * Books
   * FAQ
-  * User Manual (''see below'')
-  * Tutorials
-  * Books
-  * FAQ
-* User Manual (''see below'')
-* Tutorials
-* Books
-* FAQ
-* Get Involved
+* Get Involved (*see below*)
 * Donations
 
 There are a few other pages that follow the same conventions as a simple static page.
 
-'''User Manual''' ''The user manual is a separately compiled project, right?  In this case we can work with 
the devs on that aspect to make sure that the new static build system has what it needs in place to support 
this.''
+About the **User Manual**, we should simplify redundant data which is
+handled already by the dedicated [GIMP
+Documentation](https://docs.gimp.org/) project and redirect people
+there.
 
-It would also be in our best interests to make sure that the URL's remain the same as they've always been, 
or to carry the correct 301 redirects as needed to avoid losing any indexing-sauce that has been built up.
+About the **Get Involved** page, we should also simplify redundant data
+and redirect interested people on the current [Developer
+website](https://developer.gimp.org/).
 
-## Suggestions
+It would also be in our best interests to make sure that the URL's
+remain the same as they've always been, or to carry the correct 301
+redirects as needed to avoid losing any indexing-sauce that has been
+built up. So any change we make to a page, which involves removing or
+changing an existing URL should be accompanied by proper redirections.
 
-### Importance
+😎 [**Cool URIs don't change**](https://www.w3.org/Provider/Style/URI)!
 
-Talking with schumaml, a list of things that are most important to users visiting the page (imo):
+## Contributing to the website
+### Building the website to test locally
 
-* The project name.  Main branding.  (GIMP - The GNU Image Manipulation Program).
-* How do I get it (Download).
-* What is it (The Free &amp; Open Source Image Editor).
-* How do I use it (tutorials/docs).
-* News
-* Get Involved
-* Donate
+Our current website uses Pelican for the time being. The
+[README.md](https://gitlab.gnome.org/Infrastructure/gimp-web/-/blob/testing/README.md)
+file in the repository is pretty clear on the process to quickly build
+it for local view, which makes it extra easy to contribute.
 
-Feel free to re-order these or suggest changes as needed!
+It should be even easier when we move to Hugo, but we are not there yet!
 
-These are some ideas I (Patdavid) am considering moving forward with:
+### Content writing
 
-* The main page should serve these distinct purposes (''roughly in order of importance''):
-  * Clearly state the name of the project
-  * Clearly state the description of the project
-  * Clearly provide a means for getting the software
-  * Display recent news items/articles/blog posts
-  * Describe the program in high-level
-  * Clearly state the name of the project
-  * Clearly state the description of the project
-  * Clearly provide a means for getting the software
-  * Display recent news items/articles/blog posts
-  * Describe the program in high-level
-* Clearly state the name of the project
-* Clearly state the description of the project
-* Clearly provide a means for getting the software
-* Display recent news items/articles/blog posts
-* Describe the program in high-level
-  * Basically, anyone landing on the main page should have no doubt what they are looking at, what the 
program is for, and how to get it.
-* Try to keep the existing URL structure intact as much as possible.
-  * The only way it might not be the same going forward could be due to removal of some pages that could be 
considered extraneous.
-  * Even then, the pages should probably still exist to not break anything (just soft-remove them by no 
longer linking to them from anywhere).
-* Consolidate page information onto a single page as appropriate.
-  * For example ''Screenshots'' and ''Features'' might be better off having their information be 
presented/duplicated onto the main page.
+Most content is available in the `content/` directory. You want to
+propose tutorials, add books to our listing, propose interesting news,
+it's (nearly) all there, written in [Markdown](http://daringfireball.net/projects/markdown/)
+format. Just have a look and propose [merge
+requests](https://gitlab.gnome.org/Infrastructure/gimp-web/-/merge_requests).
+
+### Redesign
+
+There are a few possible benefits from conducting a redesign at regular
+interval:
+
+* When it helps to better organize the content
+* Modern Look
+* A chance to consider usability and ease of access for users (and to improve it)
+* Lowering the barrier to entry for new contributors/contributions.
+* Responsive Design
+
+### Technical improvements
+
+From an architecture standpoint, the general idea is to separate content from presentation.
+This is already how the previous pre-2015 website worked, how the Pelican website works and how the Hugo 
version will too.
+
+Here are some technical concepts:
+
+* Possibly having role-based permissions against different areas of a git repository (admin, presentation, 
content, tutorials, news, etc...) ([git sub-modules](http://www.git-scm.com/book/en/v2/Git-Tools-Submodules) 
were mentioned as a way to manage this).
+* The proposed idea is to separate WGO content into more user-friendly discrete pieces, such as individual 
[Markdown](http://daringfireball.net/projects/markdown/) text files.
+* These text files (+assets) are passed through a processor to be turned into static HTML assets.
+* These static HTML assets are served to users.
+
+Overall, the approach from Cristobal (who originated the discussions on
+the website redesign in a [2015
+email](https://mail.gnome.org/archives/gimp-web-list/2015-January/msg00000.html))
+considers the problem one of creating
+**Application**/**Content**/**Presentation** layers.
+
+#### Application - Role based access (git submodules)
+
+There was some original proposition to utilize [Git 
submodules](http://www.git-scm.com/book/en/v2/Git-Tools-Submodules) as a means for segregating 
content/admin/presentation from each other within a repository.
+
+It appears that this may be something that can be separately addressed later in the process of implementing 
a new site.
+Moreover we probably don't have the volume yet for this to be
+interesting, but it could become in the future, if we ever wanted to
+give maintainership to tutorials to someone, to news to someone else,
+and so on.
+
+#### Presentation
+
+With the content abstracted further to plain text files, the presentation data for WGO can be managed 
separately from the content.
+This allows not only parallel workflows but the possibility of drastic modification to the presentation 
layer without any undue burden on the content creators.
+
+The presentation layer is also something that is usually defined in terms of the static site generation (but 
can be modified/customized as needed).
+
+For pixls.us, I had used a bit of Adam Kaplan's [Grid](http://adamkaplan.me/grid/) as a basis for extending 
the site.
+This has the benefit of being a responsive design with various possible screen sizes accounted for in @media 
CSS.
+This is not a requirement, of course, but if doing a redesign we might as well consider responsive and 
mobile-first options.
+
+### From Pelican to Hugo
 
-## Pelican
+Some work is already in progress to move our static web engine from
+Pelican to Hugo.
 
+Anyone is welcome to contribute to this effort.
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]