From d38018bec209994c9c78ccbbfe0e872bf3c6867c Mon Sep 17 00:00:00 2001 From: "claude[bot]" <209825114+claude[bot]@users.noreply.github.com> Date: Fri, 20 Jun 2025 19:05:23 +0000 Subject: [PATCH 1/6] internal: add claude_feedbacks.md for writing style feedback - Create claude_feedbacks.md to collect raw feedback about Claude's writing style - Update CLAUDE.md to reference feedback file before writing new docs - Add first feedback about avoiding overly marketing language Co-authored-by: Ruben Fiszel --- CLAUDE.md | 1 + claude_feedbacks.md | 20 ++++++++++++++++++++ 2 files changed, 21 insertions(+) create mode 100644 claude_feedbacks.md diff --git a/CLAUDE.md b/CLAUDE.md index 98e5bfef5..cbc929e94 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -5,6 +5,7 @@ These guidelines ensure consistency and quality when writing or modifying Windmi ## Content - The doc should focus on the user experience, not on the engineering behind it, unless it's important (e.g. feature related to performance) +- **Before writing new documentation, review `claude_feedbacks.md` for previous writing style feedback to avoid repeating past issues** ## File structure and naming diff --git a/claude_feedbacks.md b/claude_feedbacks.md new file mode 100644 index 000000000..ae2db2147 --- /dev/null +++ b/claude_feedbacks.md @@ -0,0 +1,20 @@ +# Claude Writing Style Feedbacks + +This file contains raw feedback about Claude's writing style when creating Windmill documentation. Review these feedbacks before writing new documentation to avoid repeating past issues. + +## General Writing Style Issues + +### Overly Marketing Language (Feedback from @centdix) + +**Problem Example:** +"Windmill can automatically fill your script and flow input forms using AI to save you time and effort. This intelligent feature analyzes your form parameters and can populate them with contextually appropriate values based on your requirements." + +**Issues:** +- Too long and verbose for technical documentation +- Marketing language like "This intelligent feature" sounds promotional rather than technical +- Users prefer concise, direct explanations over flowery descriptions + +**Better Approach:** +- Keep descriptions short and technical +- Focus on what the feature does, not how "intelligent" or "smart" it is +- Use straightforward language: "Windmill can auto-fill script and flow inputs using AI" instead of verbose marketing copy \ No newline at end of file From df9f17fa8379f685d2fbc1707a5d88cf53e07af8 Mon Sep 17 00:00:00 2001 From: centdix <40307056+centdix@users.noreply.github.com> Date: Fri, 20 Jun 2025 21:11:19 +0200 Subject: [PATCH 2/6] Update CLAUDE.md --- CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index cbc929e94..f9da5ff0e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -5,7 +5,7 @@ These guidelines ensure consistency and quality when writing or modifying Windmi ## Content - The doc should focus on the user experience, not on the engineering behind it, unless it's important (e.g. feature related to performance) -- **Before writing new documentation, review `claude_feedbacks.md` for previous writing style feedback to avoid repeating past issues** +- **Before writing new documentation, review @claude_feedbacks.md for previous writing style feedback to avoid repeating past issues** ## File structure and naming From 8197f467aa2ba59e13692b31f818f2f17e3933f7 Mon Sep 17 00:00:00 2001 From: centdix Date: Mon, 23 Jun 2025 10:34:48 +0200 Subject: [PATCH 3/6] fix --- claude_feedbacks.md => writing_style_guide.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) rename claude_feedbacks.md => writing_style_guide.md (79%) diff --git a/claude_feedbacks.md b/writing_style_guide.md similarity index 79% rename from claude_feedbacks.md rename to writing_style_guide.md index ae2db2147..d07d4f134 100644 --- a/claude_feedbacks.md +++ b/writing_style_guide.md @@ -1,20 +1,22 @@ -# Claude Writing Style Feedbacks +# Claude writing style feedbacks This file contains raw feedback about Claude's writing style when creating Windmill documentation. Review these feedbacks before writing new documentation to avoid repeating past issues. -## General Writing Style Issues +## General writing style issues -### Overly Marketing Language (Feedback from @centdix) +### Overly Marketing Language -**Problem Example:** +**Problem example:** "Windmill can automatically fill your script and flow input forms using AI to save you time and effort. This intelligent feature analyzes your form parameters and can populate them with contextually appropriate values based on your requirements." **Issues:** + - Too long and verbose for technical documentation - Marketing language like "This intelligent feature" sounds promotional rather than technical - Users prefer concise, direct explanations over flowery descriptions -**Better Approach:** +**Better approach:** + - Keep descriptions short and technical - Focus on what the feature does, not how "intelligent" or "smart" it is -- Use straightforward language: "Windmill can auto-fill script and flow inputs using AI" instead of verbose marketing copy \ No newline at end of file +- Use straightforward language: "Windmill can auto-fill script and flow inputs using AI" instead of verbose marketing copy From 139520459ea5879698760daeaae635d0c3d4082f Mon Sep 17 00:00:00 2001 From: centdix Date: Mon, 23 Jun 2025 13:20:45 +0200 Subject: [PATCH 4/6] fix --- CLAUDE.md | 2 +- writing_style_guide.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index f9da5ff0e..1bf20315e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -5,7 +5,7 @@ These guidelines ensure consistency and quality when writing or modifying Windmi ## Content - The doc should focus on the user experience, not on the engineering behind it, unless it's important (e.g. feature related to performance) -- **Before writing new documentation, review @claude_feedbacks.md for previous writing style feedback to avoid repeating past issues** +- **Before writing new documentation, review @writing_style_guide.md for previous writing style feedback to avoid repeating past issues** ## File structure and naming diff --git a/writing_style_guide.md b/writing_style_guide.md index d07d4f134..f1187ef46 100644 --- a/writing_style_guide.md +++ b/writing_style_guide.md @@ -1,4 +1,4 @@ -# Claude writing style feedbacks +# Claude writing style guide This file contains raw feedback about Claude's writing style when creating Windmill documentation. Review these feedbacks before writing new documentation to avoid repeating past issues. From 63259ce2261163038b70e8456dd10e50a8c78a79 Mon Sep 17 00:00:00 2001 From: centdix Date: Mon, 23 Jun 2025 13:24:01 +0200 Subject: [PATCH 5/6] adjust --- CLAUDE.md | 2 +- writing_style_guide.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 1bf20315e..88c4e2bf0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -5,7 +5,7 @@ These guidelines ensure consistency and quality when writing or modifying Windmi ## Content - The doc should focus on the user experience, not on the engineering behind it, unless it's important (e.g. feature related to performance) -- **Before writing new documentation, review @writing_style_guide.md for previous writing style feedback to avoid repeating past issues** +- **Before writing new documentation, review @writing_style_guide.md for guidance about how to write good documentation** ## File structure and naming diff --git a/writing_style_guide.md b/writing_style_guide.md index f1187ef46..8e692dc9b 100644 --- a/writing_style_guide.md +++ b/writing_style_guide.md @@ -1,6 +1,6 @@ # Claude writing style guide -This file contains raw feedback about Claude's writing style when creating Windmill documentation. Review these feedbacks before writing new documentation to avoid repeating past issues. +This file contains writing style guidance when creating Windmill documentation. Review this guide before writing new documentation. ## General writing style issues From 795d219c6405164460d2bb1186c2080fe70420f9 Mon Sep 17 00:00:00 2001 From: Henri Courdent <122811744+hcourdent@users.noreply.github.com> Date: Mon, 30 Jun 2025 14:28:41 +0200 Subject: [PATCH 6/6] Update writing_style_guide.md Sentence case --- writing_style_guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/writing_style_guide.md b/writing_style_guide.md index 8e692dc9b..61b9ae86c 100644 --- a/writing_style_guide.md +++ b/writing_style_guide.md @@ -4,7 +4,7 @@ This file contains writing style guidance when creating Windmill documentation. ## General writing style issues -### Overly Marketing Language +### Overly marketing language **Problem example:** "Windmill can automatically fill your script and flow input forms using AI to save you time and effort. This intelligent feature analyzes your form parameters and can populate them with contextually appropriate values based on your requirements."