Use ChatGPT to smooth out docs

[mikesnoeren]

Is there an existing issue for this?

• I have searched the existing issues

Is your feature request related to a problem?

Yes, my feature request is related to a problem. The problem is that the ddev documentation is not very clear and can be difficult to understand at times, especially for users who are new to ddev or do not have a strong command of the English language. This can make it difficult for users to effectively use ddev and can lead to frustration and confusion. I would like to see the documentation improved to make it more clear and easy to understand for all users.

Describe your solution

My solution is to use an AI tool like ChatGPT to improve the clarity of the ddev documentation. By providing the original text and specifying how it should be revised, the AI can generate revised text that is clear and easy to understand. This can save time and effort compared to manually revising the documentation, and it can help ensure that the revised text is consistent and follows the same style and formatting guidelines as the rest of the documentation. I believe this would be a significant improvement and would make ddev more accessible and user-friendly for all users.

Describe alternatives

One alternative solution would be to manually revise the ddev documentation to improve its clarity. This could involve reviewing the documentation section by section and making changes to improve the language and make it more straightforward and easy to understand. However, this would be a time-consuming and labor-intensive process, and it would be difficult to ensure that the revised text is consistent and follows the same style and formatting guidelines as the rest of the documentation.

Another alternative would be to provide additional resources, such as tutorials or videos, to help users understand and use ddev more effectively. This could be useful for some users, but it would not address the issue of the documentation itself being difficult to understand.

Overall, I believe using an AI tool like ChatGPT is the best solution because it can quickly and effectively improve the clarity of the ddev documentation without requiring a significant amount of manual effort. It can also help ensure that the revised text is consistent and follows the same style and formatting guidelines as the rest of the documentation.

Additional context

To provide additional context for this feature request, I have included an example of the improved ddev documentation below. This example shows the original text and the revised text side by side, so you can see the improvements made by the AI tool.

Original text taken from the documentation:

There are two ways to remove a project from DDEV’s listing.
The first is destructive. It removes the project from DDEV’s list, deletes its database, and removes the hostname entry from the hosts file:
ddev delete <projectname>
or
ddev delete --omit-snapshot <projectname>

If you simply don’t want the project to show up in ddev list anymore, use this nondestructive command to unlist it until the next time you run ddev start or ddev config:

ddev stop --unlist <projectname>

Revised text by ChatGPT:

To remove a project from DDEV's listing, you can use either the ddev delete or ddev stop command.

The ddev delete command is destructive and will remove the project from DDEV's list, delete its database, and remove the hostname entry from the hosts file. You can use it with the following syntax:

ddev delete <projectname>

Alternatively, you can use the ddev delete command with the --omit-snapshot flag to remove the project without taking a snapshot:

ddev delete --omit-snapshot <projectname>

If you simply want to unlist the project without deleting it, you can use the ddev stop command with the --unlist flag. This will unlist the project until the next time you run ddev start or ddev config. The syntax for this command is as follows:

ddev stop --unlist <projectname>

Note that using ddev stop is nondestructive and will not delete the project or its database. It will simply unlist it from DDEV's listing.

As you can see, the revised text is clearer and easier to understand than the original text. It uses simpler language and provides more detailed explanations and examples to help users understand how to remove ddev projects. Overall, I believe this improved text would be more user-friendly and would help users get the most out of ddev.

[mikesnoeren]

Did you know that this entire github issue, including the title, description, and even this comment, was generated by ChatGPT with minimal input from a human? It just goes to show how powerful AI can be in helping us improve and automate our workflows!

[rfay]

@mattstein I thought you might be interested in this.

@mikesnoeren I have to disagree with you about the writing, I didn't feel the issue was precise, and was way too wordy.

There are some real use-cases though... when people are uncomfortable with English, for example, they can ask chatgpt to rewrite and it can do a more fluent job. However... if the folks are uncomfortable with English, they're likely not to see the errors it generates. That's been my experience with GitHub Copilot - It can generate nice-looking things that a completely wrong.

[rfay]

@mikesnoeren one request: If you have specific issues with the docs, please either fix them (click the pencil in the upper right of the page) or ask about them so somebody else can fix them.

[mikesnoeren]

@mikesnoeren one request: If you have specific issues with the docs, please either fix them (click the pencil in the upper right of the page) or ask about them so somebody else can fix them.

Yeah I will do that.. I did however find that with DDEV I rarely need the docs. Which of course is a good thing.

[mattstein]

@mikesnoeren That’s a fascinating idea, and I agree that the docs could be improved. I’ve been working for a few months on this, mostly tracked here.

My solution is to use an AI tool like ChatGPT to improve the clarity of the ddev documentation.

I think it could help in some way, but on its own it’s not going to universally improve clarity. My experience with AI—whether it’s generating code, answering questions, creating visual artwork, simulating chat, or checking grammar—is that it can be a helpful tool for a human being, but it inherently gets some things wrong and needs to be checked. It can handle the computation of a thing, but never the art of it. Someone has to review the AI revision for accuracy anyway, which is already a challenge with documentation edits coming from others but I think we’re doing a decent job of that.

This plan has to address how—not if—humans are involved, and to me it seems like it would be ideal to offer the option to have ChatGPT revise someone’s documentation PR if they’re not comfortable with the English. We could offer some mechanism for that, or even suggest it, but someone could just as well use Grammarly or some other tool for improving their writing. I’d be careful not to force its use and penalize someone who’s confident in their writing and takes the time to craft their language with precision and care.

One alternative solution would be to manually revise the ddev documentation to improve its clarity.

This is exactly what I’ve been doing with #4188, and while I’ve made good progress I’m still not done. :)

The Writing Style Guide was one of the first priorities, just as you suggest. This included a thorough sweep of the docs to make sure everything conformed to it.

“Clarity” is also a broad concept. There’s clarity of explanation, but also of overall structure and organization, conceptual clarity around fundamentals vs. specific tasks and usage, etc. Even just structuring steps or sentences so they’re easy to follow without getting lost or confused.

Another alternative would be to provide additional resources, such as tutorials or videos, to help users understand and use ddev more effectively. This could be useful for some users, but it would not address the issue of the documentation itself being difficult to understand.

Also agreed! These things take effort and time to create, and also maintain once they’re in the wild. Which takes people. Without a careful commitment there’s a risk of creating useful materials that go stale and have rapidly-diminishing value. My focus is purely on improving the clarity and utility of the documentation, but I wouldn’t stop anyone from running with other forms of learning materials!

---

If anyone wants to run documentation through ChatGPT and PR perceived improvements, great! Ultimately I think we need people carefully scrutinizing the structure, language, and presentation of the docs because that’s a human endeavor that, for the best results, can’t be left to pure automation.

While manual review and editing takes a lot of effort, I feel strongly that the resulting work will be more consistent, specific, and accurate than if left to AI.

[mikesnoeren]

Thank you for your reply, @mattstein, I totally agree with your comment.

Great job on the Writing Style Guide! It's clear that a lot of effort went into it.

It is important to clarify that my intention is not to let AI "take over" the documentation, but rather to use it to assist in rewriting certain parts, which will always be reviewed by a human for accuracy, grammar, and clarity.

I have had the opportunity to experiment with ChatGPT quite a bit, and I have found it to be helpful in writing (working!) code, emails, and in understanding complex concepts. In fact all the information in the first post in this issue was generated by the AI with only 4 lines of input, it came up with all the solutions and alternatives by itself. It does however have its quirks, so if you encounter any issues while using it, please don't hesitate to reach out to me as I am beginning to understand its way of thinking and how to influence just that..