Open ghost opened 7 years ago
@iteles and @nelsonic do you have any preference for which solution we should follow?
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!! 👍
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