Writing style

[jonasjacek]

I've noticed, that contents use different styles of writing. For example:

• https://learnlatex.netlify.app/en/lesson-01
  Heading 1 is: "What is LaTeX and how does it work?"
  • The website is asking the user a question, while it probably should inform (e.g. What LaTeX is and how it works)
• https://learnlatex.netlify.app/en/lesson-08
  Heading 1 is: "Tables"
  • A neutral statement
• https://learnlatex.netlify.app/en/lesson-03
  Heading 1 is "Your first LaTeX document"
  • Talks to the user directly
• https://learnlatex.netlify.app/en/lesson-03
  First paragraph starts with "Our first LaTeX document ..."
  • Contradicts the previous example

Thus, I struggle a bit with writing content for parts of the website which I want to create visual design for. At the same time, I am not a native speaker and thus unsure about bringing the topic up.

Maybe with this ticket I go a little way over the top, but from a use experience and accessibility perspective, I think the writing style should be consistent. What do you think?

To make things a bit more complicated:

Some contents serve specific purposes. E.g.:

• Website titles
  As they are used in front matter title: '...'
  https://www.w3.org/WAI/WCAG21/Understanding/page-titled.html
• Website headings
  As they are used to structure content (heading levels 1-6)
  https://www.w3.org/WAI/WCAG21/Understanding/headings-and-labels

I have just finished breaking up (content wise) page titles and heading level 1. That's when I realized, these should be worked on.

[dbitouze]

I think the writing style should be consistent. What do you think?

I fully agree.

[jonasjacek]

Let me suggest the following:

• Headings H1-H6
  short, objective, informative, no questions but statements, without personal address, contain important terms (SEO).
• Contents
  neutral, objective, informative, with personal address (pronouns we, you).

Also see usability.gov's tips for writing for the web, where they suggest to use pronouns.

If we use pronouns in content, we should also have some faces or at least names on the about page. Similar to https://www.latex-project.org/about/team/.

[josephwright]

I guess as an academic I find this hard ;)

I'm happy to adjust text to make it more accessible. Do you want 'us' (the various people who wrote the text thus-far) to check over for these ideas? Who do you think we should feature somewhere in 'about' - or do we merge that with the existing author list?

[jonasjacek]

I'm happy to adjust text to make it more accessible. Do you want 'us' (the various people who wrote the text thus-far) to check over for these ideas?

Yes please. At least in English (all files in /en), so English can be a blueprint for the other languages. These tips will be helpful: https://www.usability.gov/how-to-and-tools/methods/writing-for-the-web.html

Who do you think we should feature somewhere in 'about' - or do we merge that with the existing author list?

Right now there's no about page, but the mission page may be suitable. I like the general format of https://www.latex-project.org/about/team/ (small image, name, and a link or mini bio). Probably of you, David and up to four others? A small list, to keep things concise. Also, referencing the AUTHORS.md.

I will try to prepare an example today.

[dbosk]

This issue is very much related to #151.