search

dwyl / contributing

:clipboard: Guidelines & Workflow for people contributing to our project(s) on GitHub. Please :star: to confirm you've read & understood! :white_check_mark:
86 stars 9 forks source link

Content Length #83

Open ghost opened 7 years ago

ghost commented 7 years ago

The guide is very long

In fact, on this line: https://github.com/dwyl/contributing/blame/master/README.md#L463

The guide even references that it is huge.

It probably could be 1/3 the size it currently is.

Several solutions to this

  1. Go through the guide and strip unnecessary content out
  2. Create a second shorter guide for a simple, clear process reminder.
  3. We include the shorter guide at the top of the main guide, as discussed in #28
ghost commented 7 years ago

@iteles and @nelsonic do you have any preference for which solution we should follow?

nelsonic commented 7 years ago

Ciao @markwilliamfirth, thank you for the improvements you have already made to this! 😍 It's a breath-of-fresh-air to know that this guide is going to be tidied up in the coming weeks... 🌬

firstly, I totally agree that the content is way too long and needs some editorial attention. 👍

secondly, I will note that it's woefully incomplete... 😞 There a few sections that need details/elaboration/expansion in order to cover various essentials bits of info which are a "leaky bucket" for us right now ... (without a clearly defined process, the time of the Most Valuable Players of our team is methodically wasted ... which means they have less time to do the important stuff i.e. products)

finally, I wish someone else would "fill in the gaps" in the process so that I can focus on my work ... my "Todo" list is silly right now. and it would amazing if everyone else in the team followed some sort of systematic sequence of steps.

Note: we expect the process to evolve over time to be more effective, streamlined and less tedious/bureaucratic, but right now we're still in "wild west" mode where the work is being done but nobody has a clear picture of how.

To answer your question directly: We do need to condense the content of the contributing guide. (that's a given) But "stripping out" needs to be done on a section-by-section basis.

I am way more in favour of: a. updating the diagram at the top to reflect the complete sequence. pictures are way better for describing process than words! b. re-writing the entire guide to reflect the diagram. (note: the words are not to explain the diagram, they are expand on and/or give context/examples) c. splitting out the sections to match the steps in the diagram. d. *summarising the steps in a tl;dr as described/suggested by @iteles in https://github.com/dwyl/contributing/issues/28

P.S. having a lengthy description of process is not always a "bad" thing. separating the "oh that's too much to read" (people who aren't going to bother to read the 10k lines of code in a project to understand it) from the "read it, makes sense, let's get to work!" is a valuable thing ... do you want to work/eat at the restaurant where the kitchen staff follow the Michelin Star Chef's recipe or where they "free-style" it and put marmite in the chocolate mouse...? 😉 but we should never use that as an "excuse" for poor editorial or waffling/rambling content!! 👍