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.

[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 :upside_down_face:

[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 https://github.com/keirthana/ubuntu-packaging-guide/pull/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.

[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.