Documentation overhaul

A space for us to workshop ideas (maybe enabling Github Discussions later in time).

If you can't edit this page, get in touch with me (Jeremy Murphy).

Please use:

• h1 to propose a new idea,
• h2 to propose variations to an existing idea
• h3 for topics.

Problems with the existing documentation:

• fill in later...

Examples of good documentation that we might copy/steal and how they fix the identified problems:

• etc...

Make Landing Page more obvious for newcomers

Existing limitations

Newcomers struggle to build a simple graph

A newcomer who wants to simply build their first graph has to:

1. find the Table of Content link hidden in the doc landing page
2. Navigate no less than 7 sections of the ToC to reach a suitable example:
   1. Introduction to the BGL
   2. Parallel BGL
   3. History
   4. List of BGL Users
   5. Publications
   6. Acknowledgements
   7. A Quick Tour of the Boost Graph Library -> here an example of adjacency list Most of these sections sound like the BGL trying to justify itself: but users just want to be shown how to use it.

Possible solutions

1. Make the ToC the first page users land on
2. Just below the ToC put a showcase code example meant to clearly show from the start how clear the BGL syntax can be, e.g.: build a graph, print vertices and edges, and run a DFS.
3. Merge the History/List of Users/Publications/Acknowledgements into a single page About and move it toward the end of the ToC
4. Update the Introduction to the BGL section that is too long and noisy:
   • to make it less like self-justification (noise)
   • remove the analogy to the STL (noise: in 2023 we know what iterators are)
   • Make it very minimal, with only most important information:
     • 1 sentence description
     • Github Link
     • License
     • Supported compilers (?)
     • Very short example to show includes + one line of code + output
     • Important current topic (?)
     • e.g. mp-units home