Reorg on Email server documentation
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 1.4k
- Forks
- 1.2k
- Avg merge
- 9m
- Merged PRs (30d)
- 1
Description
I have a suggestion concerning the following two documents:
[Email with Postfix, Dovecot, and MySQL](https://www.linode.com/docs/email/postfix/email-with-postfix-dovecot-and-mysql/)
[Troubleshooting Problems with Postfix, Dovecot, and MySQL](https://www.linode.com/docs/email/postfix/troubleshooting-problems-with-postfix-dovecot-and-mysql/)
The "Troubleshooting" guide has two major sections, one for troubleshooting and the other being a "Step by Step Configuration" guide.
It is immensely valuable to have the _Step-by-Step_ section, as a place where the documentation can target a less experienced audience, e.g., people (like myself!) who have coding experience but are ambitious to learn about server management and configuration. For this audience, it is appropriate for the text to be more explanatory, and include extra verification steps, as opposed to the more streamlined approach taken in the main guide.
I think the overall clarity would be well-served by breaking the "Troubleshooting" guide into two separate documents, one for troubleshooting and the other being a Step-by-Step guide.
As part of this, a mention and a link to the new "Step-by-Step" guide should be in the main guide. (This can be done even now, with a link to the [Step by Step Configuration](https://www.linode.com/docs/email/postfix/troubleshooting-problems-with-postfix-dovecot-and-mysql/#step-by-step-configuration) section as it currently exists.
The intro text currently reads as follows:
> In this guide, you’ll learn how to set up a secure virtual user mail server with Postfix, Dovecot, and MySQL on Debian or Ubuntu. We’ll explain how to create new user mailboxes and send or receive email to and from configured domains.
I would propose adding a line such as the following:
> For those of you who are willing to take a longer path, we have an alternative [Step by Step Configuration](https://www.linode.com/docs/email/postfix/troubleshooting-problems-with-postfix-dovecot-and-mysql/#step-by-step-configuration) guide which breaks the task down into smaller steps while focusing on providing a deeper understanding of each component.
I certainly would have opted for this, and saved a solid week or more of time, had I known about this guide beforehand!
One additional suggestion: in the _Step-by-Step_ guide, it might be useful to include, at the beginning, an explanation of how to "reset" the system prior to commencing (i.e., making use of apt-get purge options), as an optional beginning step for those who are undertaking this guide after having attempted and failed at the main guide.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by comparing the two linked documents, especially the Troubleshooting guide's Step by Step Configuration section and the main guide's introduction. Separate the step-by-step material into its own document, link it from the main guide, and consider the proposed reset guidance; done means the guides have distinct purposes and the links and introductory text are accurate.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- mysql
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100