Skip to content

Latest commit

 

History

History
43 lines (22 loc) · 7.74 KB

Inspiration.md

File metadata and controls

43 lines (22 loc) · 7.74 KB
Raw

Articles

  • Are You Building an Outcome or Feature-Driven Roadmap? - by Denise Tilles. Takeaway: "There are a variety of ways your roadmap can express your strategic intentions. What’s important is to show how you’re driving towards outcomes. And from those strategic intentions, you’ll have initiatives that evolve from a problem into a solution."

  • Bring Kindness Back to Open Source - by Scott Hanselman. Takeaway: "There are many folks out there with skills and knowledge that are not joining open source because their initial attempts to contributed were rebuffed." Hanselman suggests ways to welcome newcomers kindly: add an Contributing.md, tag "issues with "up-for-grabs," and make an issue noting that you will "only accept a PR from someone who has never contributed to open source" (documentation adds/fixes could be great for this).

  • Creating a Strategy? Start By Generating the Best Ideas - by Tami Reiss. Takeaway: Includes a chart featuring 16 "Product Strategies for Growth" suitable for open source project maintainers. "You should run through the list as you are generating options to make sure you’ve exhausted all paths available to you. If you know you want to add new customers, grow lifetime value, or increase profitability, look at those columns to find strategies which produce that result."

  • Documentation Driven Development - by Isaac Z. Schlueter. Takeaway: "Before anything else, write down what the thing is in README.md. I use markdown, but any portable plain-text format will do. This takes three parts: The name of the thing. The 1-sentence description of what the thing is. If necessary, a few paragraphs describing the thing. Example code demonstrating how to use the thing. Note: the thing doesn’t exist yet. You do this before it exists"

  • How to Write Documentation That's Actually Useful - by Steven Vaughan-Nichols. Takeaway: "[F]our ways to make sure your applications make sense to humans as well as to computers."

  • Most Developers Think We Should Spend More Time on Documentation - by Chris Holdgraf. Takeaway: "While the data ...are a coarse measure of time for each person, they suggest that there may be a systematic under-representation of documentation in the workflows of the open source community, and that this may be tied to lower perceived appreciation and enjoyment in writing documentation. In the coming months, we hope to explore why this discrepancy might exist. Is it because of a difference in values, or skills? Are there ways that we could increase the likelihood that documentation is well-maintained (or created in the first place)?"

  • [Six Steps to Perfecting an Open Source Product Strategy](6 steps to perfecting an open source product strategy) - by Michael Dehaan. Takeaway: Six time-tested pointers for making sure your project gains users. Check out #3: "Obsess about great documentation."

  • What Does a Sustainable Open Source Project Look Like? - by Andrew Nesbitt. Takeaway: A list of standards regarding governance, documentation, code quality, support, ecosystem collaboration, security, legal, financial, marketing and dependency hygiene.

  • “Why isn’t someone using my software product or open source tool? It’s good!” - by Stephanie Hurlburt. Takeaway: A Twitter thread/checklist of project elements to consider and add so that you speak to your intended audience with software they can understand and use.

  • We did a week entirely dedicated to writing, and you should do one too. - by Harriet at Buildkite. Takeaway: Hold a dedicated Writing Week for your team to create blog posts, READMEs and other documentation.

  • You Are What You Document - by Yevgeniy Brikman. Takeaway: "The number one cause of startup failure is not the product, but the distribution: it doesn’t matter how good the product is if no one uses it. With software, the documentation is the distribution: it doesn’t matter how good the code is if no one uses it. If it isn’t documented, it doesn’t exist."

Projects

  • Awesome README - by Matias Singers. Takeaway: an Awesome List for all things README-related.

  • Beautiful Docs - by Mark Phillips. Takeaway: "a list of docs and other developer resources that [Phillips] and others find particularly useful, well-written, and otherwise 'beautiful.'"

  • CodeWerdz Project - by Troy Howard and Nik Blanchet. Takeaway: "We would like to see developer culture shift from a code-centric model, where the code is considered the most important thing, to a product-centric model, where the code is considered just one component of a shippable product, which also includes unit tests, and documentation."

Standards

  • Standard Readme - by Richard Litt. Takeaway: "Writing READMEs is way too hard, and keeping them maintained is difficult. By offloading this process—making writing easier, making editing easier, making it clear whether or not an edit is up to spec or not—you can spend less time worry about whether or not your initial documentation is good, and spend more time writing and using code."

Videos

  • Communication Is Just as Important as Code - by Andrea Goulet, NEJS 2016. Takeaway: "The idea of a lone developer coding in their basement without social interaction is a thing of the past. These days, technical solutions are often developed by cross-functional teams whose participants have a range of technical experience. Now, more than ever, good communication skills are an essential part of being a software developer. In this talk, Andrea will share immediately actionable communication principles that will help you; get buy-in for your ideas, reduce conflict and tension, increase productivity, be liked and respected."

  • Documentation Avoidance for Developers - by Peter Hilton, J-Fall 2016 + TopConf Tallinn 2016. Takeaway: "This talk explores what we talk about when we talk about code, how we do it, and the tools we use. You can often find a better tool than documentation, but not always. Not everyone writes detailed specifications these days, but remote working and distributed teams make written explanations more valuable than ever. Talking face to face requires less effort, but you rarely or never meet the authors of most of the code you see. Software craftsmanship has failed to make written documentation unnecessary. Instead we shall turn to README-Driven Development, comments evasion, documentation-avoidance, just-in-time documentation and the art of not writing it in the first place."

  • How to Write Documentation for People that Don't Read - Kevin Burke, Write the Docs 2015. Some realistic advice here.