Reorganize content page

[The-Compiler]

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.rst and fixture.rst) is hidden on examples.rst but not mentioned at all in content.rst.

Some other stuff in content.rst is 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!

[Zearin]

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!

[nicoddemus]

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. 😁