: Designing source code documentation I'm looking to design a modern website for a C++/Javascript library. While I have several ideas in mind I wanted to know what are some good design strategies

@Hamm6457569

Docpad is one of my personal favorites, especially the implementation used by SemanticUI which gives the option of demonstration displays, or keeping things short and simple.

Ideally documentation should have a few key elements


Grouping of articles with common themes
Clear and meaningful titles. Rather than using the function names as a title, use the intended use instead.
A brief description of what should happen, and what it is used for
A short code sample, of how to implement it
In UI affecting functions, a demonstration of how it should look and work
In the case of style guidelines a do/don't example
Any caveats that may be encountered


Always bear in mind that the documentation may be read by an intern when they start working with the project, so get into their mindset whilst developing it. Ask whether it would be simple to find what you're looking for, is it easily understandable, and does it show how to use it?

Vote Up Vote Down