Repository navigation
Reorganize content page #1112
Description
Activity
I came to this repo hoping to see if I was missing an easier-to-navigate piece of documentation (or any helpful GitHub Wiki content).
Definitely 👍 on this.
I do not have the free time to contribute at the moment, but if I can make a suggestion...
I find that the best documentation tends to have content organized something like this:
- Guides: step-by-step instructions on accomplishing the most common tasks.
- These are useful to newcomers and early-to-intermediate users.
- They should contain stuff like “How to Install”, “Your First Project”, and “Going Further”.
- Sometimes they contain stuff like “Advanced Uses” or “Kung-Fu Tricks”, which are useful for advanced users.
- Quick Reference: a list of things for fast lookup, usually human-written.
- These are useful to everyone. (Even advanced programmers regularly look stuff up! ☻)
- They should contain stuff like (in PyTest’s case), “Command Line Reference”, “INI Config Reference”, “conftest.py”, “List of PyTest Decorators”, “Markers Reference”, and “PyTest Special Variables” (listing all cases that require PyTest to find a specially-named variable in a specific place to make it do something).
- There may be plenty of overlap between “Quick Reference” and the other two sections. The distinguishing feature is that these tend to be organized as “get in, get out” info. Depending on the project, they may tend to be written as lists, glossaries, simple diagrams, or cheat sheets.
- A “Conceptual Overview” is also useful here. This should give a “10,000 foot overview” of the project’s major components and their roles.
- Full Reference/API Docs: the complete documentation or API, usually generated.
- These are useful to advanced users and developers. They contain the nitty-gritty to anything the code is capable of.
That’s as much time as I can spare to help. Wish I had time for more!
- Guides: step-by-step instructions on accomplishing the most common tasks.
Thanks for taking the time to write this down! This was somewhat what I had in mind (and I suspect @The-Compiler as well), so it is good to have it in writing so we don't forget anything. 😁
- added 5 commits that reference this issue
on Aug 23, 2016
I always found the pytest docs quite hard to navigate - and because of someone with the same issue in IRC just now I realized why: The stuff which is probably most relevant (
assert.rstandfixture.rst) is hidden onexamples.rstbut not mentioned at all incontent.rst.Some other stuff in
content.rstis probably not that relevant... I think the whole thing should have some reorganization.I'll take a look in a few weeks (still have a growing todo list), but if someone else wants to pick this up, please go ahead!