develop a documentation strategy for an embedded software engineering group that mainly…
- User
develop a documentation strategy for an embedded software engineering group that mainly deals with Git, C++ and Visual Studio Code
Assistant
Here is a suggested documentation strategy for an embedded software engineering group using Git, C++ and Visual Studio Code:
-
Use Markdown files in the code repository to document key aspects of the codebase. Place documentation alongside the code it relates to. Use a README.md file to provide overview documentation for each module/component.
-
Maintain a project wiki using a tool like GitHub/GitLab wikis to provide higher level documentation - overview of architecture, key concepts, getting started guides etc. Wikis make it easy to link to docs in the codebase.
-
Document code inline using comments following standard conventions like Doxygen. Use tags to mark functions, classes, warnings etc. Enable Doxygen documentation generation.
-
Use Visual Studio Code markdown preview and extensions like Doxygen Generator to seamlessly write and preview documentation alongside code.
-
Document code dependencies, build instructions, testing procedures etc using markdown/Doxygen comments in the repository. Use README files at root and subfolders.
-
Write a comprehensive Developer Guide using Markdown that explains the overall architecture, design principles, code structure, build processes, testing guidelines etc. Store this in the wiki or docs folder.
-
Use diagrams and visuals extensively for architecture, component interactions, state machines etc. Store these in the wiki or docs folder and link from documentation.
-
Document processes for documentation - use templates, follow standards, review docs regularly, get feedback from team members.
-
Use a style guide for consistent formatting of documentation across the codebase.
-
Automate documentation generation from code comments using Doxygen, markdown parsing etc.
-
Consider a hosted wiki like Confluence to publish and track versions of higher level documentation while maintaining docs close to code in the repository.
-
Other models, same or similar prompt
Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.