Message256033
David, I love the three paragraph intro. It captures the essence of the dev guide usage from newcomers to the project to experienced core devs. I really like the second paragraph and how it suggests focusing on the issue at hand. Thanks, and I will take these three suggested paragraphs and rework the patch.
I'll use the three paragraphs as an intro, circular file the quickstart, and rework some of the remaining content into its own section(s).
I respect how you like a quality Table of Contents when looking for information. Alternatively, other folks use search extensively to find information, and search gives a different, less linear walk through the document. So I think it is reasonable to err on the side of a quality uncluttered Table of Contents.
However, I also do think that those that are new to the project are looking for a bit more guidance. Though I concur that the guidance does not need to be in a quickstart; though it should be in an easily discoverable place. Quickstarts are common on other open source projects so new contributors will likely look for one (or something similar). What new contributors are looking for are brief pathways (i.e. a few steps toward productivity) specific to documentation, testing, issue triaging, etc. Whether called pathways or a quickstart isn't critical, what is important is guiding those that need more assistance and those that don't have the time privilege to read the devguide in its entirety.
Thanks for the suggestions. I'll make another pass at it. :D |
|
Date |
User |
Action |
Args |
2015-12-06 21:41:10 | willingc | set | recipients:
+ willingc, brett.cannon, ezio.melotti, r.david.murray, sjt |
2015-12-06 21:41:10 | willingc | set | messageid: <1449438070.01.0.121317040115.issue24682@psf.upfronthosting.co.za> |
2015-12-06 21:41:09 | willingc | link | issue24682 messages |
2015-12-06 21:41:09 | willingc | create | |
|