loading...

re: As a Team, How Do You Share Your Knowledge? VIEW POST

FULL DISCUSSION
 

Some have mentioned Confluence here, or some other wiki. Having done my fair share in the CMS world, here are some suggestion/comments:

  • You will find MANY online blog posts or comments that basically say "Confluence is where documents go to die". However, this is not the tools fault, but rather the implementation and ongoing maintenance.

  • if you have a small team, develop a consistent category and tagging methodology up front and try to stuck to it. Things can easily get out of control, and a search engine will not help.

  • If you can, develop some common templates for the documentation. This will ensure you have consistent information, and you can clearly see where you have gaps. This also allows other developers to jump in to fill the gaps where they can.

  • Documentation is not a replacement for comments in code. "just read the code" is a symptom of "cowboy coding" and doesn't help the overall team --especially if you add new people to the team.

  • If you use a documentation generator (Sphinx, Swagger, etc) be sure you actually add in all the annotations so there is more than just code examined. Explain WHY you did something, why the business logic is as it is, etc.

  • Write the documentation. Period. The person you are benefiting may be YOU six months down the road when you look back and forget what the heck you were thinking when you wrote that code.

Code of Conduct Report abuse