{"id":524824,"date":"2024-11-11T16:11:57","date_gmt":"2024-11-11T15:11:57","guid":{"rendered":"https:\/\/blog.jetbrains.com\/?post_type=writerside&p=524824"},"modified":"2024-11-11T16:33:02","modified_gmt":"2024-11-11T15:33:02","slug":"writing-docs-with-code-samples-try-out-the-new-writerside-eap-release","status":"publish","type":"writerside","link":"https:\/\/blog.jetbrains.com\/zh-hans\/writerside\/2024\/11\/writing-docs-with-code-samples-try-out-the-new-writerside-eap-release","title":{"rendered":"Writing Docs With Code Samples? Try Out the New Writerside EAP Release"},"content":{"rendered":"\n

Each Early Access release is designed to make writing documentation easier and more enjoyable. This update is based on your feedback and focuses on improving code blocks<\/a>, but there is more<\/a>! Thank you all for sharing your ideas. It\u2019s a pleasure to keep improving our product for you.<\/em><\/p>\n\n\n

\n
\n Download Writerside<\/a>\n <\/div>\n <\/div>\n\n\n\n\n\n\n\n

Code samples in documentation: Stick to the basics<\/h2>\n\n\n\n

When I first started thinking about presenting code samples in technical documentation, the initial idea was about advanced features, like interactivity, robust linking between text and code, and sophisticated presentation options, such as substituting placeholders on the fly. <\/p>\n\n\n\n

However, the recent Unconference session at the Write The Docs Atlantic conference<\/a> revealed something surprising \u2013 the most pressing concerns regarding code blocks weren’t about cutting-edge features, but about getting the fundamentals right<\/mark>.<\/p>\n\n\n\n

\"\"<\/figure>\n\n\n\n

Reality check: Know your audience<\/h2>\n\n\n\n

At the conference, the discussion quickly shifted from “How can we make our code samples more interactive?” to “What does our audience actually need?” This pivot highlighted a fundamental truth in technical writing: understanding your readers’ goals is more important than implementing cutting-edge features.<\/mark><\/p>\n\n\n\n

The 4 key insights regarding code blocks<\/h2>\n\n\n\n
    \n
  1. Context and purpose<\/strong><\/li>\n<\/ol>\n\n\n\n

    It\u2019s not about \u201cshort\u201d versus \u201clong\u201d code samples \u2013 what matters is context and purpose. Tutorials need complete, real-world examples. API docs benefit from focused code blocks that demonstrate specific functionality. <\/p>\n\n\n\n

      \n
    1. Copy-paste is the reality <\/strong><\/li>\n<\/ol>\n\n\n\n

      There\u2019s no way around it \u2013 regardless of experience level, people consistently copy and paste code samples. We can\u2019t fight it, but we can use code blocks that are complete enough to work even when directly copy-pasted, or that indicate what to do to make them work. <\/p>\n\n\n\n

      As Chris Chinchilla points out in “Technical Writing for Software Development”<\/a>, developers frequently copy and paste a series of code snippets into an editor because it’s a fundamental part of learning.
      <\/p>\n\n\n\n

        \n
      1. Different strokes for different folks<\/strong><\/li>\n<\/ol>\n\n\n\n

        Code samples serve as learning material, and, like any other learning resource, one size does not fit all \u2013 different learning styles<\/a> call for different examples. Beginners might need step-by-step breakdowns, while expert developers might prefer more comprehensive examples that they can tweak to fit their own needs without much hassle.<\/p>\n\n\n\n

          \n
        1. Complementary tools<\/strong><\/li>\n<\/ol>\n\n\n\n

          Swagger specs and Postman collections are great companions to documentation, but not replacements. They help users move from learning to doing, once the concepts are clear.<\/p>\n\n\n\n

          Code block maintenance: The hidden challenge<\/h2>\n\n\n\n

          As products evolve, keeping code samples up to date is crucial \u2013 and challenging.<\/p>\n\n\n\n