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 the Landing Page more friendly

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 display an example to showcase how concise 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 it is too long and noisy:
   • 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

Better navigation simple features

Existing limitations

Newcomers struggle with simple features, e.g. modifying vertex property

This stems from several reasons:

• The "right" example code is difficult to locate in the BGL documentation
• Examples are pre-C++11
• Useful snippets of code are diluted in text, making it harder to identify sections of interest
• Navigation in the doc is difficult, as returning to the top-level ToC is cumbersome or not possible

Possible solution

1. Make a permanent link to the top-level ToC (homepage) on every documentation page
2. Simple features seem to be listed in the A Quick Tour of the Boost Graph Library page, but it could be made easier to navigate:
   • remove the illustration comparing with STL (noise)
   • remove most of the text (noise): for example "First we can access all of the vertices in the graph using the vertices() function of the VertexListGraph interface. This function returns a std::pair of vertex iterators (the first iterator points to the "beginning" of the vertices and the second iterator points "past the end")": this is just noise.
   • Add self-contained examples for each purpose a new user may have in mind:
     • build a graph
     • add edges
     • in_edges vs out_edges
     • add vertices properties
     • add edges properties
   • Do NOT split example codes, this makes copy pasting nasty: for newcomers it is better to have some repetition than having them scroll to find the missing parts of the code that would make their example compile ...
   • Make all these examples easily discoverable by summarizing them in a page-ToC at the top