[lgkk]

In the repo, readme. Mostly.

Each of my repos have an overview, installation, execution, testing, and deployment sections.

I include images or links to Lucid for architecture diagrams.

Sometimes I put readme into subdirectories as well if I think it’s warranted. (Rare)

I really like markdown. It’s a great format for sharing information for technical folks especially newcomers to the code.

As for documenting code itself, I try my best to write simple, clear, self explanatory code with good naming. All of my functions are single responsibility. Everything is clean and organized whether it’s structs or classes.

I rarely write comments in code unless it’s for autodoc’ing library code.

Not sure if this is what you were asking for - let me know if you mean something else. Interested to know more.

[chairleader]

Thanks for the reply, I'm also a big fan of documentation living inside the repo. I appreciate the framework you describe for the readme as well. Similar to _kb's sibling comment, that sounds like a sane approach to meeting the needs of contributors to and supporters of the codebase.

FWIW, I'm struggling with documentation that support the mix of roles on the team in addition to coders/contributors - QA engineers, product owners, project managers, support teams, etc. A big part is the capture of requirements flowing into proposed solutions and out into support documentation.

In reply to _kb, it did occur to me that there are many job descriptions at play here, and that change is inevitable. Perhaps the answer is simply that it takes many people and several genres of software to keep things from falling through the cracks.

[lgkk]

For sure.

I know JIRA isn't everyone's cup of tea, but it reminded me of Confluence since you mentioned people across domains like that. I only mentioned JIRA because it was connected to Github and other services (sales, marketing, designers, etc.) and that made it easy for people across domains to discuss and have common place for everyone on a project and share information in a meaningful way.

The knowledge lived in one space together, so it was kind of cool that I would pull some data from our data sets to help marketing frame their messaging. Or seeing designers and product managers work together on mocks and share customer insights, and then product engineering teams would build their tickets from it. I could get an insight into what work the technical teams are doing and help them deploy their software.