My feedback on https://github.com/causes-tracker/designdocs/blob/master/Manifesto.md

gistfile1.md

Manifesto feedback

Intro

This is my feedback on the Causes manifesto. The points are numbered for easier discussion, and are a mix of questions, suggestions, observations and so forth. I'd like to actually have a stab at applying them.

I think a good way of incorporating this feedback is for me to make the following set of patches: a. Change Manifesto.md to wrap at 78 columns b. Apply the formatting / grammar fixes c. Do the more daring rewrites

The actual feedback

1. start with something like lifeless's slide from architecture presentation (what are surprising things that will be true about a project that uses Causes)

2. I don't like the name "Causes", either as a code name or as a final name

3. Stats is a key thing

4. Don't open with the data model before getting into Why

5. I haven't heard of "project timeline" and am interested in its rationale

6. Italicize technical terms on first mention

7. Do good bug trackers really make a difference to projects? Is there evidence? How can we disprove this assumption?

8. I guess it'd be good to start with what problems bug trackers are intended to solve, and then specify which of these Causes is intended to solve / not solve. It's my understanding that Causes is intended to rethink the entire category.

9. I'd split the "Should we contribute" bit into a subsection of Why

10. "a significant number of 'what if' questions" -- I'd like to see them enumerated!

11. By the time I've reached the MVP section, I'd like to see a list of things we believe that we would like to falsify, e.g. "A bug tracker that separates observed issues with a project from human-reported issues will ...". Bullet point or enumerate them.

12. "Signs" and "Symptoms" are basically synonyms in English ("a sign of an infection" and "a symptom of an infection" mean pretty much the same thing). It's unfortunate that we are using these words to distinguish two different concepts.

13. Footnotes are broken

14. MVP section is duplicated and badly formatted

15. Please enumerate / code-name the "Features"

16. The bullet points in "Dedicated user, dev..." are gold, and are exactly the things I'd put into a list of things we believe (ref #11)

17. The 'not validated' comment is useful. One key output of this manifesto will be a list of things we need to validate

18. By the time I've got up to "Does one thing well", I've realized that "Features" is not actually a Features section

19. I think it's worth unpacking why a bug tracker isn't a project management tool (because lots of people use bug trackers to do project management, and lots of people think that bug trackers should do project management)

20. I like "Work with your bugs on the road" and "Work privately with a public project's bugs" sections

21. However, the grammar of those titles is different from "Dedicated user...", "Sensible assumptions" and "Does one thing well"

22. Also, is this a pitch to potential users or a rallying cry to inspire and focus the builders? There's a non-trivial amount of overlap, but I would contend that a manifesto should be the latter, and that some of these sections lean more toward the former.

23. "Integrates with your existing data" is exciting! (but also has dodgy formatting)

24. It refers to principles. They should come before this section.

25. "Clean and lean" section of Implementation is badly formatted.

26. I really wish there were a better way of tracing these assertions to whether or not we've validated them & how.

27. I think "Weak consensus decision making" doesn't say very much, but meh.

28. Link to Canvas is broken. Also, isn't this manifesto how we assess the project?

29. Maybe add something about evidence-driven decisions?

30. The "Values" are pretty key, and I think are referred to elsewhere as princples. I like the name principles better.

31. Give these values names that can be referred to. This is done in the "Integrates..." feature, but the names aren't echoed here.

32. Add an intro to "Archetypes" quickly explaining what this is for

33. Perhaps Archetypes should be moved to a separate design doc?

34. Architecture & UI should definitely be moved to separate docs

35. At least one of the archetype users should dual roles (e.g. contributes to free software under an alias but is employed)