Improve home page

[keirthana]

• Move the community engagement details from reference topic to home page and delete the reference topic.
• Make minor improvements to structure of home page.

@dviererbe This is a first attempt at redoing the home page to align better with our documentation practice. There are some pending points to be considered:

• What is the discourse link that we would want to include under the Project and Community heading?
• I have moved contents of the reference communication topic to the homepage as it provides more visibility on the home page. It also nicely aligns with our motivation to promote community engagement.
• Is the information about mailing lists and IRC channels up to date? I just took them from the existing reference topic.

Also, a request to add the .pre-commit-config.yaml to the overhaul branch so that the pre-commit checks can be run.

[s-makin]

Generally LGTM :) although I think some of the questions you raised are probably better answered by the others, it's an undeniable improvement.

Do we want to include the traditional "line breaking at 79 characters" policy that I've seen elsewhere, or is it not needed here?

[s-makin]

I think it's important to specifically call out the code of conduct/draw attention to it by separating it off: I prefer it as a bullet point (although I'm not sure it would make sense here with only one bullet point!)

[keirthana]

With the current reformat, a separate bullet point does not make sense but I did make it the beginning of a paragraph to garner more attention, WDYT?

[s-makin]

These channels do still exist and are still used. I'm not sure if there are any other channels that should be included - or any that the Community team would like us to add. Could be worth checking with Aaron?

[dviererbe]

thought: The problem is that it depends on what you want to do in Ubuntu. Recommending those two in general seems fine to me.

---

issue: We have to explain to beginners what "MOTU" (Masters of the Universe, see https://wiki.ubuntu.com/MOTU) is.

thought: I thought of adding a glossary (https://sublime-and-sphinx-guide.readthedocs.io/en/latest/glossary.html) for terms like MOTU, FTBFS, NBS, ... that show up frequently in Ubuntu communication. Maybe we should even add a small glossary for slang abbreviations like ACK, IIRC, AFAICT, ... Because they confused the heck out of me when I started.

[s-makin]

That's a great idea!

[keirthana]

Glossary is a good idea. For now, I have included the link and the expanded form of MOTU.

[s-makin]

We will probably want to update the source of this link, since this still points to Launchpad. Although the Launchpad version will still be there - Dave or Dominik can probably confirm which is the best to use.

[dviererbe]

note: @waveform80 is currently working on this, but I think the link will not change. The current binary package is just outdated.

[keirthana]

Generally LGTM :) although I think some of the questions you raised are probably better answered by the others, it's an undeniable improvement.

Do we want to include the traditional "line breaking at 79 characters" policy that I've seen elsewhere, or is it not needed here?

I tried checking on this and there's line breaking at 79 and then at 119 characters. Which one do we want to follow? I checked some files but not sure if this has been followed consistently with all files. Maybe worth checking in the meeting tomorrow?

[s-makin]

Generally LGTM :) although I think some of the questions you raised are probably better answered by the others, it's an undeniable improvement.
Do we want to include the traditional "line breaking at 79 characters" policy that I've seen elsewhere, or is it not needed here?

I tried checking on this and there's line breaking at 79 and then at 119 characters. Which one do we want to follow? I checked some files but not sure if this has been followed consistently with all files. Maybe worth checking in the meeting tomorrow?

Good idea - I don't think it was followed consistently before, but if we're re-writing everything from scratch it's the perfect time to decide what style we want to follow 🙃

[dviererbe]

As just discussed in the meeting, I opened a Pull Request to update & extend the Communication Channel References.

[dviererbe]

• Move the community engagement details from reference topic to home page and delete the reference topic.
• Make minor improvements to structure of home page.

@dviererbe This is a first attempt at redoing the home page to align better with our documentation practice. There are some pending points to be considered:

• What is the discourse link that we would want to include under the Project and Community heading?

• I have moved contents of the reference communication topic to the homepage as it provides more visibility on the home page. It also nicely aligns with our motivation to promote community engagement.

• Is the information about mailing lists and IRC channels up to date? I just took them from the existing reference topic.
  Also, a request to add the .pre-commit-config.yaml to the overhaul branch so that the pre-commit checks can be run.

praise: I really like what you did here. Also +1 on adding the pre-commit checks.

[dviererbe]

Generally LGTM :) although I think some of the questions you raised are probably better answered by the others, it's an undeniable improvement.
Do we want to include the traditional "line breaking at 79 characters" policy that I've seen elsewhere, or is it not needed here?

I tried checking on this and there's line breaking at 79 and then at 119 characters. Which one do we want to follow? I checked some files but not sure if this has been followed consistently with all files. Maybe worth checking in the meeting tomorrow?

Good idea - I don't think it was followed consistently before, but if we're re-writing everything from scratch it's the perfect time to decide what style we want to follow upside_down_face

thought: I would like to have a formatting policy like:

• max line lengths (doesn't have to be 79 characters; we don't live in the 80s)
• empty new line at end of file
• no trailing whitespace at end of line
• two (or more) consecutive empty lines should be avoided
• exceptions are okay, if they improve readability

[dviererbe]

note: before I delete my notes on Ubuntu communication; here is the remaining stuff that I did not put into keirthana#1 Maybe you find it useful or want to partially include it:

• IRC Chats get recorded here: https://irclogs.ubuntu.com/
• The IRC Channel #ubuntu-meeting may be interesting as many teams use this channel to discuss Ubuntu related topics.
• There are also Canonicals Mailing Lists: https://lists.canonical.com/mailman3/postorius/lists/
• If you subscribe to high-volume bug mailing lists; there are custom e-mail headers that can be used to filter emails https://wiki.ubuntu.com/Bugs/HowToFilter
• Should we write a tip that there are a lot of e-mails sent in the mailing lists and they should create E-Mail filters? It took me the good part of a day to create my e-mail filters.

[keirthana]

note: before I delete my notes on Ubuntu communication; here is the remaining stuff that I did not put into keirthana#1 Maybe you find it useful or want to partially include it:

* IRC Chats get recorded here: https://irclogs.ubuntu.com/

* The IRC Channel `#ubuntu-meeting` may be interesting as many teams use this channel to discuss Ubuntu related topics.

I have added this since it seems like something that will help a beginner.

* There are also Canonicals Mailing Lists: https://lists.canonical.com/mailman3/postorius/lists/

* If you subscribe to high-volume [bug mailing lists](https://lists.ubuntu.com/#Bug+Lists); there are custom e-mail headers that can be used to filter emails https://wiki.ubuntu.com/Bugs/HowToFilter

* Should we write a `tip` that there are a lot of e-mails sent in the mailing lists and they should create E-Mail filters? It took me the good part of a day to create my e-mail filters.

I have included a tip in general and followed it up with the bug mailing list example.

[s-makin]

This all looks good to me. Thanks for all your work on this :)

The only thing I wanted to ask about (although it's not a blocker to merging) is about the change to the header markers. The original order used (##, ==, --) is from the general Python documentation style guide. I know you've been working on the style guide stuff, so if you've managed to dig up a better convention for us to follow in your sleuthing, would you mind writing up a style guide page for anyone who wants to contribute specifically to the docs? (again, doesn't need to be in this PR, but would be really great to have :D)

[dviererbe]

@keirthana You can go ahead and merge if you want. I have one last Nitpick, but that is just a preference on my side.

Praise: Thanks for your effort :)

[dviererbe]

Last Nitpick; I think the description for #ubuntu-meeting is more accurate this way, but this is just my preference:

Suggested change

	any of the `IRC channels`_. You may find especially these channels useful in the beginning:
	* ``#ubuntu-devel``, for general development discussion
	* ``#ubuntu-motu``, for `Masters of the Universe`_ (MOTU) team discussion and generally getting help.
	* ``#ubuntu-meeting``, for discussions on Ubuntu and related topics.
	any of the `IRC channels`_. You may find especially these channels useful or interesting in the beginning:
	* ``#ubuntu-devel``, for general development discussion
	* ``#ubuntu-motu``, for `Masters of the Universe`_ (MOTU) team discussion and generally getting help
	* ``#ubuntu-meeting``, meetings are held here by various Ubuntu teams (everyone is welcome to participate)

Note: In the future, I also want to replace the MOTU term explanation by a reference to the (not yet existing) glossary.

[keirthana]

Makes sense, I will make this change and merge it. And yes, agree on moving common terminology to the Glossary later on.

[keirthana]

This all looks good to me. Thanks for all your work on this :)

The only thing I wanted to ask about (although it's not a blocker to merging) is about the change to the header markers. The original order used (##, ==, --) is from the general Python documentation style guide. I know you've been working on the style guide stuff, so if you've managed to dig up a better convention for us to follow in your sleuthing, would you mind writing up a style guide page for anyone who wants to contribute specifically to the docs? (again, doesn't need to be in this PR, but would be really great to have :D)

I followed the reStructuredText style guide here, I am not sure if there is a standard one we follow. This is kinda my first experiment with reStructuredText. We should definitely discuss and decide on a style guide that we are going to follow - Canonical's or something else? Canonical's can be minimal considering the scope and scale of this guide but also could be a good place to start with.