Re: [Boost-users] [Graph] [Documentation] What are best practices on user-friendly documentation?

From: Doug Gregor (dgregor_at_[hidden])
Date: 2006-04-10 15:44:31

On Apr 10, 2006, at 11:03 AM, Greg Link wrote:

> Boost-List -
> 	About a week ago, I wrote to the list, asking for some basic
> assistance getting the boost Graph library utilized in a short sample
> program. One of the list members (Dmitry Bufistov) was kind enough to
> show me the problem areas in my sample program, and now I've got
> everything working quite nicely. My question, then is this: Would it
> be a 'good' thing to try to append the 93-line sample program I
> posted (now working properly) to the documentation regarding the
> boost Graph library? Given that the current dijkstra_shortest_paths
> example doesn't show instantiation of a non-constant path, nor does
> it show accessing said graph, would a more 'user friendly' example
> help others in the future?

Absolutely!

> 	In general, my only problems with the boost libraries so far have
> been documentation related, so I'm eager to see future users have
> better access to information. What's the consensus regarding such
> 'user-friendly' examples, and how would I go about getting something
> added to the documentation if such examples are considered a 'good'
> thing?

If you could submit a patch to the documentation, someone (for the  
BGL, it would be me) will review the patch and put it in Boost CVS  
for an upcoming release. Users like yourself are the best people to  
write this kind of documentation, because you know where we made the  
mistakes in the current documentation. Those of us that have been  
writing BGL algorithms for years see things very differently.

        Doug