valueflows docs
git clone
Log | Files | Refs | README

commit 3d0146f8a7c965af66566b83cb24540b43039def
parent 75622411f48a0d4167483e099684ef3473a146d1
Author: Lynn Foster <>
Date:   Thu, 15 Oct 2015 18:25:48 -0500

Merge pull request #50 from valueflows/contributing

first pass at
Diffstat: | 116+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 116 insertions(+), 0 deletions(-)

diff --git a/ b/ @@ -0,0 +1,116 @@ +# Contributing to Value Flows + +This project is open commons that anyone can improve. + +We welcome all contributions, such as but not limited to: + +- visual designs +- documentation +- artwork +- use cases +- code +- discussions +- tests + +If you contribute enough, you'll be invited to join the project members. + +Value Flows aims for autonomous solving of collaborative problems with a common vision. + +## Workflow + +Value Flows follows the ["GitHub Flow"]( workflow for using [our GitHub repos]( + +* Anything in the master branch is deployable +* To work on something new, create a descriptively named branch off of master (i.e. fairy-princess-use-case) +* Commit to that branch locally and regularly push your work to the same named branch on the server +* When you need feedback or help, or you think the branch is ready for merging, open a pull request +* After someone else has reviewed and signed off on the feature, you can merge it into master +* Once it is merged and pushed to ‘master’, you can and should deploy immediately + +## Philosophy + +Value Flows aims for simplicity by merging iterative patches that minimally solve [agreed-upon problems](./ + +> The _Simplicity Oriented Design_, or SOD, process starts with a realization: we do not know what we have to make until after we start making it. Coming up with ideas or large-scale designs isn't just wasteful, it's a direct hindrance to designing the truly accurate solutions. The really juicy problems are hidden like far valleys, and any activity except active scouting creates a fog that hides those distant valleys. You need to keep mobile, pack light, and move fast. +> +> SOD works as follows: +> +> - We collect a set of interesting problems (by looking at how people use technology or other products) and we line these up from simple to complex, looking for and identifying patterns of use. +> - We take the simplest, most dramatic problem and we solve this with a minimal plausible solution, or "patch". Each patch solves exactly a genuine and agreed-upon problem in a brutally minimal fashion. +> - We apply one measure of quality to patches, namely "Can this be done any simpler while still solving the stated problem?" We can measure complexity in terms of concepts and models that the user has to learn or guess in order to use the patch. The fewer, the better. A perfect patch solves a problem with zero learning required by the user. +> - Our product development consists of a patch that solves the problem "we need a proof of concept" and then evolves in an unbroken line to a mature series of products, through hundreds or thousands of patches piled on top of each other. +> - We do not do anything that is not a patch. We enforce this rule with formal processes that demand that every activity or task is tied to a genuine and agreed-upon problem, explicitly enunciated and documented. +> - We build our projects into a supply chain where each project can provide problems to its "suppliers" and receive patches in return. The supply chain creates the "stop mechanism" because when people are impatiently waiting for an answer, we necessarily cut our work short. +> - Individuals are free to work on any projects, and provide patches at any place they feel it's worthwhile. No individuals "own" any project, except to enforce the formal processes. A single project can have many variations, each a collection of different, competing patches. +> - Projects export formal and documented interfaces so that upstream (client) projects are unaware of change happening in supplier projects. Thus multiple supplier projects can compete for client projects, in effect creating a free and competitive market. +> - We tie our supply chain to real users and external clients and we drive the whole process by rapid cycles so that a problem received from outside users can be analyzed, evaluated, and solved with a patch in a few hours. +> - At every moment from the very first patch, our product is shippable. This is essential, because a large proportion of patches will be wrong (10-30%) and only by giving the product to users can we know which patches have become problems that need solving. +> +> SOD is a hill-climbing algorithm, a reliable way of finding optimal solutions to the most significant problems in an unknown landscape. You don't need to be a genius to use SOD successfully, you just need to be able to see the difference between the fog of activity and the progress towards new real problems. +> +> People have pointed out that hill-climbing algorithms have known limitations. One gets stuck on local peaks, mainly. But this is nonetheless how life itself works: collecting tiny incremental improvements over long periods of time. There is no intelligent designer. We reduce the risk of local peaks by spreading out widely across the landscape, but it is somewhat moot. The limitations aren't optional, they are physical laws. The theory says, this is how innovation really works, so better embrace it and work with it than try to work on the basis of magical thinking. +> +> And in fact once you see all innovation as more or less successful hill-climbing, you realize why some teams and companies and products get stuck in a never-never land of diminishing prospects. They simply don't have the diversity and collective intelligence to find better hills to climb. When Nokia killed their open source projects, they cut their own throat. +> +> A really good designer with a good team can use SOD to build world-class products, rapidly and accurately. To get the most out of SOD the designer has to use the product continuously, from day one, and develop his or her ability to smell out problems such as inconsistency, surprising behavior, and other forms of friction. We naturally overlook many annoyances, but a good designer picks these up and thinks about how to patch them. Design is about removing friction in the use of a product. +> +> In an open source setting, we do this work in public. There's no "let's open the code" moment. Projects that do this are in my view missing the point of open source, which is to engage your users in your exploration, and to build community around the seed of the architecture. +> +> - [How to Design Perfect (Software) Products]( + +## Developer's Certificate of Origin 1.0 + +By making a contribution to this project, I certify that: + +* (a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license indicated + in the file; or +* (b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source license + and I have the right under that license to submit that work with + modifications, whether created in whole or in part by me, under the + same open source license (unless I am permitted to submit under a + different license), as indicated in the file; or +* (c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified it. + +## Code of Conduct + +This Code of Conduct is adapted from [Node.js's wonderful +CoC]( + +* We are committed to providing a friendly, safe and welcoming + environment for all, regardless of gender, sexual orientation, + disability, ethnicity, religion, or similar personal characteristic. +* Please avoid using overtly sexual nicknames or other nicknames that + might detract from a friendly, safe and welcoming environment for + all. +* Please be kind and courteous. There's no need to be mean or rude. +* Respect that people have differences of opinion and that every + design or implementation choice carries a trade-off and numerous + costs. There is seldom a right answer. +* Please keep unstructured critique to a minimum. If you have solid + ideas you want to experiment with, make a fork and see how it works. +* We will exclude you from interaction if you insult, demean or harass + anyone. That is not welcome behavior. We interpret the term + "harassment" as including the definition in the [Citizen Code of + Conduct](; if you have any lack of + clarity about what might be included in that concept, please read + their definition. In particular, we don't tolerate behavior that + excludes people in socially marginalized groups. +* Private harassment is also unacceptable. No matter who you are, if + you feel you have been or are being harassed or made uncomfortable + by a community member, please contact one of the channel ops or any + of the TC members immediately with a capture (log, photo, email) of + the harassment if possible. Whether you're a regular contributor or + a newcomer, we care about making this community a safe place for you + and we've got your back. +* Likewise any spamming, trolling, flaming, baiting or other + attention-stealing behavior is not welcome. +* Avoid the use of personal pronouns in code comments or + documentation. There is no need to address persons when explaining + code (e.g. "When the developer") + +## Changes to this arrangement + +This is an experiment and feedback is welcome! This document may also be subject to pull requests or changes by contributors where you believe you have something valuable to add or change.