1 point by docqueen 1 year ago flag hide 12 comments
theck 1 year ago next
I keep my project documentation in a Git repo along with the code. I use Markdown files to write the docs, and version control keeps everything in sync.
johnfd 1 year ago next
That's a sensible approach. For smaller projects, I often use Google Docs to store documentation. It makes collaborating with non-technical team members easier and allows for real-time comments.
brikero 1 year ago prev next
We maintain our documentation as wiki pages on our project management platform. The platform can integrate directly with our version control system (Git) so updating both is straightforward.
dwt 1 year ago next
I like the idea of integrating documentation with the version control, but I stumbled on a problem. People need to sign off on the docs too. We use Confluence because we can require users to digitally sign before approving the documentation.
timcd 1 year ago next
@dwt That's a problem on which we haven't found the ideal solution yet. We also need to get stakeholders and clients to sign off. Currently we add new files in the Git repo, add a 'signed-off' tag, commit and push.
matfen 1 year ago prev next
Our team lives in Slack and Jira. So, we just link to project documentation in comments and tickets. This setup works okay, although people might miss some of the docs. This is the main drawback of this approach.
toddk 1 year ago next
How do you integrate Slack and Jira with documentation in Git or a wiki? Automating link sharing sounds useful!
matfen 1 year ago next
@toddk We faced same issue and used a third party webhook service that listens to specific commit events and post link in the Jira ticket using Slack API with appropriate channel mentioned in ticket.
ag_47 1 year ago prev next
We use an internal Markdown-based documentation tool that offers Git integration. So, the documentation is source-aware, revision-controlled, and entirely managed within Git repositories.
ananth_mg 1 year ago next
That sounds neat! Have you faced any documentation overload with Markdown files in the Git repo? How do you handle keeping the documentation clean?
ag_47 1 year ago next
@ananth_mg Not really. We've established best practices to avoid overloading. New documentation needs proper naming conventions and folder placement. Consistency contributes much to keeping it clean.
scutte 1 year ago prev next
How actor.rest.ch implemented their documentation:<br/><a href='https://actor.rest/posts/en/latest/internals/ docs/'>https://actor.rest/posts/en/latest/internals/docs/</a>