Add context to index.rst and docs categories #1671
Conversation
| Getting Started | ||
| --------------- | ||
|
|
||
| Your next steps depend on where you're standing: |
There was a problem hiding this comment.
Skimming over the web3.py docs I noticed that the docs are using the second person "you" form a lot so I'm not suggesting to change it here. I just wanted to point out that the majority of our other projects use the first-person "we" form. There's no right or wrong, it's just a matter of picking one and staying consistent. I just wanted to point it out and draw your attention to our little guide line on docs: https://github.com/ethereum/snake-charmers-tactical-manual/blob/master/documentation.md#narrative-perspective
But then again, I'm not suggestion to change the narrative perspective for web3.py, I just wanted to raise awareness that this is slightly different then e.g. what Trinity uses.
There was a problem hiding this comment.
Thanks for highlighting this. I like to keep a casual tone, but I'm probably guilty of some inconsistency, so I'll keep an eye on it. Indeed the rest of the docs (or at least the few pages I just scanned) utilize the "you" form, so seems reasonable to continue the trend. If we decide to change course at some point, I won't fight it too hard ;)
cburgdorf
left a comment
cburgdorf
left a comment
There was a problem hiding this comment.
I think this is a major improvement! It looks much more welcoming and organized! Anyone being curious can checkout the generated preview at: https://web3py--1671.org.readthedocs.build/en/1671/
2 participants
What was wrong?
The index page of the docs is (naturally) the most visited page in the documentation, but it does little for our cause as an unstructured table of contents dump.
How was it fixed?
Added some introductory text, next step links, and broke the pages into three categories.
This content is a starting point. Opinions desired.
Todo:
Cute Animal Picture