Features List: Examples of other projects with great documentation

[TKorr]

I thought I'd help out by giving a few links to other open source projects with great documentation that I have come across. Learning from good examples would be a good start. This list is by no means exhaustive so please add more...

Python
what to like:

• simple
• good use of white space
• consistent style and format throughout
• can flip between versions
  built with: Sphinx

Pandas
what to like:

• excellent examples
• whole section displayed in one page instead of multiple pages
• table of contents stays open (but doesn't track with the scroll bar which is a pain)
• can flip between versions
  built with: Sphinx

scikit-learn
what to like:

• lots of description for each section with examples, great for learning
• provides reference material in each section
• a flowchart to help guide
  starters
• can flip between versions
  built with: Sphinx

Django
what to like:

• starts with a tutorial
• consistent style
• provides a how-to-guide
• simple color pallette
• can flip between versions
  built with: Sphinx

Trac
what to like:

• table of contents stays the same on every page so you can navigate around quickly
• very simple layout
• uses color in line with branding
  built with: Trac Wiki

Ceph
what to like:

• use of a colour scheme that relates to the logo/branding
• mostly about setting it up getting it working quickly, separates details out to another section
• separate architecture section
  built with: Sphinx, reST

Angular
what to like:

• separated table of contents uses drop-downs to give users flexible navigation
• has a cheat sheet
  built with: not sure, couldn't find it in the docs!

Others:
MongoDB
git
Chef
Ansible
D3

Further possible actions to take:

• Decide on a color scheme, how will it differ between projects/repo/components but still retain the IPFS brand
• Decide on a schema, or a "separation of concerns" for documentation. how do we separate out each area of communication for different users whilst maintaining consistency across the repos
• Decide on which set of tools to use, Sphinx, wiki, reST etc...

[cwaring]

Hi @TKorr, thanks for taking the time to list out these! We're gearing up for a new documentation upgrade so I've added your notes to our review list –perhaps a little late but appreciated all the same :)