Skip to content

completely refactor README & parts of docs#3097

Merged
georglauterbach merged 10 commits intomasterfrom
improvement/docs
Feb 19, 2023
Merged

completely refactor README & parts of docs#3097
georglauterbach merged 10 commits intomasterfrom
improvement/docs

Conversation

@georglauterbach
Copy link
Copy Markdown
Member

@georglauterbach georglauterbach commented Feb 17, 2023

Description

I removed many parts of the README and placed them inside the docs. This is done to ensure we can properly version all of out documentation. I believe that users should generally always use our documentation, not a mixture of README + docs, to configure and check their mail server. This makes maintenance easier for maintainers, and changes are local to the version. Previously, we had to keep the README and docs in sync, which is undesirable.

I took many parts of the README and copy-pasted it into the docs. Other parts were slightly adjusted to match the context. The landing page of our docs was more heavily refactored and updated to display more information.

I also added notes on the versioning of the docs!

There is actually more work to do in cleaning up parts of the docs (a section in the examples chapter needs overhaul, etc.). But I did want to make this PR bigger - it is big enough.


@polarathene please, by all means, go ahead and apply suggested changes immediately without waiting for me. I'd only just apply them anyway :) This way we can make reviewing faster. I hope you think the changes a worthwhile.

Type of change

  • Improvement (non-breaking change that does improve existing functionality)

Checklist:

  • My code follows the style guidelines of this project
  • I have performed a self-review of my own code
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation (README.md or the documentation under docs/)

I removed many parts of the `README` and placed them inside the docs.
This was done to ensure we can properly version all of out
documentation. I believe that users should generally **always use our
documentation**, not a mixture of `README` + docs, to configure and
check their mail server. This makes maintenance easier for maintainers
as well as changes are local to the version. Previously, we had to keep
`README` and docs in sync, which is undesirable.

I took many parts of the READMe and copy-pasted it into the docs. Other
parts were slightly adjusted to match the context. The landing page of
our docs was more heavily refactored and updated to display more
information.

I also added notes on the versioning of the docs!

There is actually more work to do cleaning up parts of the docs (a
section on the examples chapter needs overhaul, etc.). But I did want to
make this PR bigger - it is big enough.
@georglauterbach georglauterbach added kind/improvement Improve an existing feature, configuration file or the documentation area/documentation labels Feb 17, 2023
@georglauterbach georglauterbach added this to the v12.0.0 milestone Feb 17, 2023
@georglauterbach georglauterbach self-assigned this Feb 17, 2023
@georglauterbach
Copy link
Copy Markdown
Member Author

@wernerfred I you have the time, please provide me with some feedback and whether you think this is a good idea :)

Comment thread docs/content/examples/tutorials/basic-installation.md Outdated
@wernerfred
Copy link
Copy Markdown
Member

@wernerfred I you have the time, please provide me with some feedback and whether you think this is a good idea :)

it absolutely is!

Previously, we had to keep the README and docs in sync, which is undesirable.

Finally, we should have done that much earlier!

The landing page of our docs was more heavily refactored and updated to display more information.

It reads fantastic now imho. Much cleaner and futureproof!

Thanks a lot!

wernerfred
wernerfred previously approved these changes Feb 18, 2023
Copy link
Copy Markdown
Member

@wernerfred wernerfred left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚀

Copy link
Copy Markdown
Member

@polarathene polarathene left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great work tackling this 😀

I'll apply my suggestions via the web UI.

Comment thread docs/content/index.md Outdated
Comment thread docs/content/examples/tutorials/basic-installation.md Outdated
Comment thread docs/content/examples/tutorials/basic-installation.md Outdated
Comment thread docs/content/examples/tutorials/basic-installation.md Outdated
Comment thread docs/content/examples/tutorials/basic-installation.md Outdated
Comment thread docs/content/examples/tutorials/basic-installation.md Outdated
Comment thread docs/content/examples/tutorials/basic-installation.md Outdated
Comment thread docs/content/examples/tutorials/basic-installation.md Outdated
Comment thread docs/content/examples/tutorials/basic-installation.md Outdated
Comment thread docs/content/examples/tutorials/basic-installation.md Outdated
polarathene
polarathene previously approved these changes Feb 19, 2023
Copy link
Copy Markdown
Member

@polarathene polarathene left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM 👍

@github-actions
Copy link
Copy Markdown
Contributor

Documentation preview for this PR is ready! 🎉

Built with commit: 14d5032

@georglauterbach
Copy link
Copy Markdown
Member Author

I resolved the conflicts and will merge it now :)

@georglauterbach georglauterbach merged commit 8533013 into master Feb 19, 2023
@georglauterbach georglauterbach deleted the improvement/docs branch February 19, 2023 12:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/documentation kind/improvement Improve an existing feature, configuration file or the documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants