0

In my intership I used the D3.js framework to visualize data, now at the end of the internship I'm going to write a documentation about the project as a whole. Only few people in my team have been involved in the project. None of them were involved in the JavaScript writing. As far as I know not many know how to write (good) JavaScript. Since I was fairly new to JS, I probably didn't write the best code and I was sometimes rather confused by the D3.js approach to join data.

Should I try and explain how the data binding in D3.js works (Eventhough I might get it wrong) or should I just refer to the official documentation?
Is there any benefit if I try to explain it? E.g. someone who knows JS better than me sees why I did something the way I did it and can fix / improve it?

I'm not talking about inline documentation. It is an external documentation, that should explain all the components, technologies, etc. Example: How does the integration of Java, JavaFX and JavaScript work?

3
  • Possible duplicate of What's wrong with comments that explain complex code?
    – gnat
    Commented Sep 30, 2016 at 8:15
  • see also: Methodology for documenting existing code base
    – gnat
    Commented Sep 30, 2016 at 8:15
  • 1
    Link to the external documentation. Somebody already wrote it and is presumably maintaining it. You have no reason to essentially create a backup image of their docs. You may want to just document any specific quirks or integration details that you may have had to deal with that will save the rest of your team time in the future but don't just replicate external docs.
    – Jason C
    Commented Sep 30, 2016 at 9:15

2 Answers 2

Reset to default
2

In my opinion:

  • first of all, you should put information what libraries/frameworks you used in your application (name, version number, url to such library)
  • you should also describe how your application is working, how code is organised, what methods/functions you used etc. So you should give general description of your works and your idea behind the application (please remember to put some diagrams / screens - not only raw text)
  • but there is no sense to explain how D3.js or any other library/plugin/framework is working. This can be checked in official documentation.

BTW. it is also good to use some solution for code documenting for example: http://usejsdoc.org

5

Don't explain how the framework works. That is already done in their official documentation (assuming they have a good one).

Instead, you should explain how are you using it, assuming that the person reading the documentation has read the framework's documentation.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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