How to use DeepWiki, Readme files and user documentation?

[lisa-tarbo]

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-tarbo]

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

[lisa-tarbo]

Hi team

As a less technical person I have empathy with non-tech readers of user docs.

OCS User docs have pages of OAuth, Python nodes, Meta Cloud API, Custom actions which are very technical. And pages that are for Analysts about concepts and specific features they can use.

Our user docs say "you don't need to be an engineer to get started." ;-)

So i have a few options of how to structure the docs for our users who have different ability and roles.
Let me know your thoughts

Structure on Content Types (what we have)

ie How to guides and Concepts
So we can add other menus like:

• Tutorials (for beginners and users who do analysis and setting up basic chat bots) and How to Guides can be problem orientated and technical if necessary
• Reference (for code examples and tech notes that concept docs can link to so very tech info is not on same page as product/concept info). Could also call this "Developer Docs" or "Tech Hub"

Progressive Disclosure of Technical Complexity

Keep your "Setup" and "Configuration" sections separated in the sidebar. Use "Advanced" dropdowns or toggles within articles to hide complex code snippets unless the user explicitly clicks to see them. This keeps the interface clean for non-technical reviewers.

Implement Visual "Audience Tags"

At the top of every article, use a consistent badge or callout box to indicate the required RBAC role and technical level.

[SmittieC]

@lisa-jwayela you make a good point, thanks for pointing it out.

My 2c:

• I don't think it matters too much which approach we take, as long as it's clear where new content should go and what audience each section is for. I can see a small readme be very useful here.
• Personally I'm leaning towards the first approach, since we already use how to and concepts.

[snopoke]

@lisa-jwayela this is great and thanks for thinking though this. I'm very open to making these kind of changes. I do think our original documentation structure could be improved.

[lisa-tarbo]

The menu structure I am working with

[snopoke]

Great. Tutorials and How-to-guides seem quite similar. Could they be merged?

[lisa-tarbo]

Here is what I learnt @snopoke from Gemini!

If we get the structure right for us, then easier to keep consistent when extending user guides

Structure on Content Type

The Diátaxis Framework, is widely considered the "gold standard" for modern technical documentation (used by projects like Ubuntu, Python, and Django).

Its core philosophy is that documentation is not a single thing. Instead, it is a collection of four different types of writing that serve four distinct human needs. When you mix these types (e.g., putting a long "Why this works" explanation in the middle of a "How-to" guide), the user gets frustrated because their "mental mode" is interrupted.

1. Tutorials (Learning-oriented)

The User’s Goal: "I want to learn how to use this."
The Content: A lesson that leads a beginner from zero to a small, successful outcome.
The Rule: Do not explain why something works here; just show them how to do it.

2. How-To Guides (Problem-oriented)

The User’s Goal: "I have a specific task to finish."
The Content: A recipe. A series of steps to achieve a real-world goal
The Rule: Assume the user already knows the basic terminology. Don't teach; just solve.

3. Reference (Information-oriented) - I called this Tech-Hub

The User’s Goal: "I need the technical facts."
The Content: Dry, encyclopedia-style descriptions. API endpoints, etc.
The Rule: Be brief, accurate, and structured (tables are your friend here).

4. Explanation (Understanding-oriented) - This is our Concepts

The User’s Goal: "I want to understand the concepts."
The Content: Background, design philosophy, and "the big picture."
The Rule: This is the only place where you are allowed to be "chatty." Use diagrams and talk about the "Why."

[snopoke]

That all sounds right @lisa-jwayela based on this how do you think we should proceed?

[lisa-tarbo]

I like alignment on direction to improve readability - thanks @snopoke

First step is to review PR as this is the start of moving the pages into new menu structure. If this is a good-enough start
dimagi/open-chat-studio-docs#312

Then going forward, I will adjust current content to this structure. Sometimes separating out some content into new pages and into new menus.

PS: Then I can move from fork to clone and it will make PRs easier

[lisa-tarbo]

In the contributing to User Docs page, I added a section to explain what type of content should be in each menu section to ensure this pattern is continued : https://developers.openchatstudio.com/contributing/user_docs/#how-to-make-good-user-docs-changes