How to use DeepWiki, Readme files and documentation?

[lisa-jwayela]

Hi - I am Lisa.
A ex developer and an ex Dimagi employee. I am learning about LLMs and AI assisted dev workflows, so building, using and understanding this product has value for me. I want to contribute where I can.

I found the OCS DeepWiki while working to improve the Readme docs. https://deepwiki.com/dimagi/open-chat-studio

I would like to hear opinions on how to create useful docs considering all the AI tools that make it easier

1. Deepwiki - seems amazing for developers with lots of detail and diagrams What is the accuracy of this generated content?
2. Readme files are used by DeepWiki, so I see them still valid but shifting to include the why, background, context, assumptions, constraints, and provide structure to the deepwiki generated.
3. User documentation is essential. What if we link Readme to user docs, then will deepwiki pick this up?
4. Developer docs (https://developers.openchatstudio.com/) need to link all knowledge together to assist easy onboarding
5. How do we make sure the knowledge provided in https://github.com/dimagi/open-chat-studio/blob/main/AGENTS.md is also useful to improve our documentation?
6. Would it be useful to add a .devin/wiki.json file that allows us to steer Devin’s default wiki generation behavior ?

If there is an agreed on approach to improving documentation, then I can follow your best practices

[snopoke]

1. Deepwiki - seems amazing for developers with lots of detail and diagrams What is the accuracy of this generated content?

I would generally consider it to be accurate.

2. Readme files are used by DeepWiki, so I see them still valid but shifting to include the why, background, context, assumptions, constraints, and provide structure to the deepwiki generated.

That's correct - documentation should focus on why and procedural, not so much on implementation details which change and become out of date quickly.

3. User documentation is essential. What if we link Readme to user docs, then will deepwiki pick this up?

Not that I'm aware of.

4. Developer docs (https://developers.openchatstudio.com/) need to link all knowledge together to assist easy onboarding

Is that a question?

5. How do we make sure the knowledge provided in https://github.com/dimagi/open-chat-studio/blob/main/AGENTS.md is also useful to improve our documentation?

This file has a very specific purpose which is to give global context to AI agents when they are working on the project.

6. Would it be useful to add a .devin/wiki.json file that allows us to steer Devin’s default wiki generation behavior ?

I haven't looked at this at all so I'm not sure. I haven't looked at Deepwiki in a while.

If there is an agreed on approach to improving documentation, then I can follow your best practices

User docs are probably the most useful thing to contribute to. I'm sure there is plenty that is unclear or missing from our user docs. We've generally taken a 'better some docs than no docs' approach without significant thought to overall structure so we could also consider broader structural changes. (docs repo at https://github.com/dimagi/open-chat-studio-docs)

[lisa-jwayela]

Thanks Simon for your thoughts

From more research I can confirm

• Deepwiki does analyze the whole repo so includes markup, in-code comments and even config files :-)
• Reviews suggest its accuracy is somewhere between 60-80% accurate
• README files and AGENTS.md for example will add to wiki accuracy
• Inaccurate README files could impact wiki accuracy
• I agree that README should focus on why/rationale and procedural (also assumptions and risks if appropriate)
• I agree that user docs important for terminology, feature clarity etc so these give developers context to the code

I will share PRs for doc updates based on this discussion