From 516d7bccc92e54e16eae25d2bcc2702bafa5a1ab Mon Sep 17 00:00:00 2001 From: pashpashpash Date: Wed, 16 Jul 2025 15:37:24 -0700 Subject: [PATCH] adding documentation workflow (#4598) * adding documentation workflow * Update .clinerules/workflows/writing-documentation.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * good example * good example * language * Update writing-documentation.md * Update writing-documentation.md * Update writing-documentation.md * Update writing-documentation.md * Update writing-documentation.md * Update writing-documentation.md * Update writing-documentation.md * Update writing-documentation.md * Update writing-documentation.md * Update writing-documentation.md * Update writing-documentation.md * Update writing-documentation.md * Update writing-documentation.md * Update writing-documentation.md --------- Co-authored-by: Cline Evaluation Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../workflows/writing-documentation.md | 392 ++++++++++++++++++ 1 file changed, 392 insertions(+) create mode 100644 .clinerules/workflows/writing-documentation.md diff --git a/.clinerules/workflows/writing-documentation.md b/.clinerules/workflows/writing-documentation.md new file mode 100644 index 0000000000..61cf6cc036 --- /dev/null +++ b/.clinerules/workflows/writing-documentation.md @@ -0,0 +1,392 @@ +# General writing guide + +# How I want you to write + +I'm gonna write something technical. + +It's often less about the nitty-gritty details of the tech stuff and more about learning something new or getting a solution handed to me on a silver platter. + +Look, when I read, I want something out of it. So when I write, I gotta remember that my readers want something too. This whole piece? It's about cluing in anyone who writes for me, or wants me to write for them, on how I see this whole writing product thing. + +I'm gonna lay out a checklist of stuff I'd like to have. It'll make the whole writing gig a bit smoother, you know? + +## Crafting Compelling Titles + +I often come across titles like "How to do X with Y,Z technology." These don't excite me because X or Y are usually unfamiliar unless they're already well-known. Its rarely the dream to use X unless X is the dream. + +My dream isn’t to use instructor, its to do something valueble with the data it extracts + +An effective title should: + +- Evoke an emotional response +- Highlight someone's goal +- Offer a dream or aspiration +- Challenge or comment on a belief +- Address someone's problems + +I believe it's more impactful to write about specific problems. If this approach works, you can replicate it across various scenarios rather than staying too general. + +- Time management for everyone can be a 15$ ebook +- Time management for executives is a 2000$ workshop + +Aim for titles that answer questions you think everyone is asking, or address thoughts people have but can't quite articulate. + +Instead of "How I do something" or "How to do something," frame it from the reader's perspective with "How you can do something." This makes the title more engaging. Just make sure the difference is advisory if the content is subjective. “How I made a million dollars” might be more reasonable than “How to make a million dollars” since you are the subject and the goal might be to share your story in hopes of helping others. + +This approach ultimately trains the reader to have a stronger emotional connection to your content. + +- "How I do X" +- "How You Can do X" + +Between these two titles, it's obvious which one resonates more emotionally. + +You can take it further by adding specific conditions. For instance, you could target a particular audience or set a timeframe: + +- How to set up Braintrust +- How to set up Braintrust in 5 minutes + +## NO adjectiives + +I want you to almost always avoid adjectives and try to use evidence instead. Instead of saying "production ready," you can write something like "scaling this to 100 servers or 1 million documents per second." Numbers like that will tell you exactly what the specificity of your product is. If you have to use adjectives rather than evidence, you are probably making something up. + +There's no reason to say something like "blazingly fast" unless those things are already known phrases. + +Instead, say "200 times faster" or "30% faster." A 30% improvement in recommendation system speed is insane. + +There's a 200 times performance improvement because we went from one programming language to another. It's just something that's a little bit more expected and understandable. + +Another test that I really like using recently is tracking whether or not the statements you make can be: + +- Visualized +- Proven false +- Said only by you + +If you can nail all three, the claim you make will be more likely to resonate with an audience because only you can say it. + +Earlier this year, I had an example where I embedded all of Wikipedia in 17 minutes with 20 bucks, and it got half a million views. All we posted was a video of me kicking off the job, and then you can see all the log lines go through. You see the number of containers go from 1 out of 50 to 50 out of 50. + +It was easy to visualize and could have been proven false by being unreproducible. Lastly, Modal is the only company that could do that in such an effortless way, which made it unique. + +## Keep It Digestible + - Aim for 5-minute reads + - Write at a Grade 10 reading level + - Break up long paragraphs + - Use headers and bullet points + +## Make It Scannable + - Bold key points + - Use subheadings every 3-4 paragraphs + - Include plenty of white space + - Add relevant examples + +This structure works whether you're writing a tweet thread or a full blog post. The key is making complex ideas accessible. + +# Guide to Writing Cline Documentation + +## Some general principles for explaining features + +If you're talking about a feature, it's helpful to start with a human-readable explanations that cover what the feature is in simple terms. Skip jargon and explain it like you're talking to someone who's never seen it before. This sets the foundation for everything that follows. + +Combine location and usage into one flowing section. Tell users exactly where to find the feature and how to use it, but weave the instructions into natural prose with a good balance of bullet points, numbered lists, code examples (if applicable), mintlify components, and headers/subheaders. Users shouldn't have to jump between separate "where is it" and "how do I use it" sections. + +Show the feature in action with real examples like actual files, workflows, or code. Users need to see concrete implementations, not just abstract descriptions. This is where understanding turns into practical knowledge. + +When talking about a feature, include an inspiration section that sparks imagination. This section pushes people from understanding to action by showing them what becomes possible when they use this feature creatively. It's what separates good documentation from great documentation. + +## Writing Principles That Actually Work + +### Write for Action, Not Just Understanding + +Documentation should motivate users to try things. Instead of just explaining how something works, focus on what users can accomplish with it. The inspiration section is crucial - it's what transforms passive readers into active users. + +### Create a Natural Story Flow + +It should feel like a conversation that naturally progresses from "what is this?" to "how do I use it?" to "here's a real example" to "imagine what you could do with this." + +### Show Real Examples, Not Toy Demos + +Provide actual workflow files, real code snippets, and concrete implementations that users can copy and adapt. Abstract examples don't help anyone - users want to see exactly what they'll be working with. + +### Keep It Scannable But Not Fragmented + +Write in prose that flows naturally when read completely, but structure it so users can quickly find specific information when they're troubleshooting. Avoid dense walls of text, but also avoid over-formatting with excessive bullet points and bold headers. There should be a nice visual heirarchy of balance between all elements, so you can quickly scan the page and find what you're looking for. + +## Language and Tone Guidelines + +Write clearly without dumbing things down. Use simple language when possible, but don't avoid technical terms that users need to know. Explain concepts in terms of what users can achieve rather than how the software works internally. + +Make your writing conversational and encouraging. Phrases like "you can also try" or "when that works" feel more natural than rigid instructional language. Help users feel confident about trying new things. + +Keep content concise and purposeful. Every sentence should either help users understand something or help them do something. If it doesn't serve one of those purposes, cut it. + +Build in context and reasoning. Users want to understand why they're doing something, not just what to do. This builds confidence and helps them troubleshoot when things don't work exactly as expected. + +## Practical Implementation + +Structure each feature page consistently with the four-section approach, but let the content flow naturally within that structure. Use visual assets like videos and screenshots to complement the written content - they often communicate more effectively than paragraphs of description. + +Link generously to related resources, examples, and deeper documentation. Users should never feel stuck or wonder where to go next. Maintain a repository of real examples that users can reference and adapt to their own needs. + +The goal is documentation that feels more like helpful guidance from an experienced colleague than a technical manual. Users should finish reading feeling excited about what they can accomplish, not just informed about what the feature does. + +## Balance Structure with Flexibility + +While they discuss having consistent documentation structure, there's also mention of making content feel less rigid and more natural. The writing should follow guidelines while still feeling conversational and engaging. + +## Bad examples + +I personally hate this pattern of bullet point **Bold Text** colon and then more text: + +#### macOS + +1. **Switch to bash**: Go to Cline Settings → Terminal → Default Terminal Profile → Select "bash" +2. **Disable Oh-My-Zsh temporarily**: If using zsh, try `mv ~/.zshrc ~/.zshrc.backup` and restart VSCode +3. **Set environment**: Add to your shell config: `export TERM=xterm-256color` + +#### Windows + +1. **Use PowerShell 7**: Install from Microsoft Store, then select it in Cline settings +2. **Disable Windows ConPTY**: VSCode Settings → Terminal › Integrated: Windows Enable Conpty → Uncheck +3. **Try Command Prompt**: Sometimes simpler is better - switch to cmd.exe + +#### Linux + +1. **Use bash**: Most reliable option - select in Cline settings +2. **Check permissions**: Ensure VSCode has terminal access permissions +3. **Disable custom prompts**: Comment out prompt customizations in `.bashrc` + + + +We should instead strive to write beautiful docs that read well. We can use bullet points and numbered lists but it should read naturally and be delightful to look at hierachally when scanning through the doc. There should be a good balance between blocks of text, code snippets, paragraphs, numbered lists, and bullet points. When scanning the documentation visually, you should feel like you're adminiring a tasteful art piece. + + +#### macOS + +The most common fix is switching to bash. Navigate to Cline Settings → Terminal → Default Terminal Profile and select "bash" from the dropdown. + +If you're still having issues, Oh-My-Zsh might be interfering with terminal integration. Try temporarily disabling it: +- Run `mv ~/.zshrc ~/.zshrc.backup` +- Restart VSCode + +You can also add `export TERM=xterm-256color` to your shell configuration file to improve compatibility. + +#### Windows + +PowerShell 7 provides the most reliable experience. Install it from the Microsoft Store, then select it in your Cline settings. + +Still seeing problems? Try these solutions: +- Disable Windows ConPTY: VSCode Settings → Terminal › Integrated: Windows Enable Conpty → uncheck +- Switch to Command Prompt (cmd.exe) - sometimes simpler shells work better + +#### Linux + +Bash is your most dependable option. Select it in Cline settings if you haven't already. + +Check these common issues: +- Ensure VSCode has terminal access permissions +- Temporarily comment out custom prompt configurations in your `.bashrc` + + +This is much more natural to read. Writing this way creates a conversational flow, and bullet points are used idiomatically. + +# Using Mintlify Components Idiomatically + +Mintlify's custom components can transform basic documentation into engaging, scannable content that users actually want to read. Here's how to use them effectively. + +## Visual Content with Frames + +Videos and images should be wrapped in `` components rather than using raw HTML or markdown. This creates consistent styling and proper responsive behavior. + +For videos, embed them directly rather than linking externally. Users are much more likely to watch a 30-second demonstration than click through to another platform: + +```jsx + +