Skip to content

Instantly share code, notes, and snippets.

@vcostin

vcostin/documentation_guidelines.md

Last active December 30, 2025 14:36
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save vcostin/83bcae3e3ee5fd1916f7762bd56e3314 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save vcostin/83bcae3e3ee5fd1916f7762bd56e3314 to your computer and use it in GitHub Desktop.
Download ZIP
📜 Console‑First Documentation: A Developer’s Guideline
Raw
documentation_guidelines.md

📜 Console‑First Documentation: A Developer’s Guideline

1. Documentation Creates Practice

  • The way official docs present solutions shapes how developers work.
  • If the only path shown is “navigate and click,” that becomes the default practice — even when a simpler, scriptable path exists.
  • Developers deserve to see both: GUI for casual users, console for automation.

2. Console Is a Developer’s Friend

  • Console commands are reproducible, automatable, and transparent.
  • A one‑liner installer (curl, Invoke-WebRequest, apt-get) saves hours compared to navigating GUIs.
  • Windows developers should be empowered with the same console‑first culture that Linux/macOS communities take for granted.

3. Frustration Pills vs. Hidden Gems

  • Many Windows tools do have command‑line installers (e.g., Visual Studio Build Tools).
  • But they’re buried in enterprise deployment docs, not developer quick‑starts.
  • This mismatch creates unnecessary frustration: the “real simple path” is hidden, while the marketed path feels bloated.

4. Principles for Better Documentation

  • Always show the console alternative alongside GUI instructions.
  • Respect developer time: highlight minimal, scriptable installs.
  • Be transparent: admit complexity when it exists, don’t hide it behind marketing.
  • Normalize automation: treat console commands as first‑class citizens, not niche hacks.

5. The Cultural Shift

  • Windows can be a powerful developer platform, but only if its documentation embraces automation.
  • Console‑first examples don’t alienate non‑technical users — they empower technical ones.
  • By making automation visible, documentation sets a healthier practice: reproducible, minimal, authentic.

6. Frustration Flavors: A Case Study

Not all frustration looks the same, but the root cause is often poor onboarding culture.

  • Zend Framework 2 (PHP): Documentation explained what the framework was but not how to work with it.

    • Developers struggled with incomplete guides.
    • Commercial courses were offered instead of fixing docs, which alienated the community.
    • Result: Symfony, with clear and practical documentation, won adoption while Zend faded.

  • Rust on Windows: Documentation is strong overall, but setup friction (toolchains, hidden console installers) punishes developers.

    • The problem isn’t the language, but the platform‑specific onboarding.
    • The “real simple path” (PowerShell one‑liner) exists but is buried.

Common thread: When documentation hides simplicity or clarity, frustration builds early and leaves sour memories.
Good docs empower; bad docs punish.

🚀 Closing Thought

Documentation isn’t just about teaching commands. It teaches culture.
If we want developers to thrive, console‑first practices must be visible, not hidden.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment