0

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 for representing source code documentation. Particularly, I'm looking for some modern examples of great looking and easy to follow source code docs around the web.

2

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?

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.