Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[chore] Restructure developer docs #855

Open
andrewnicols opened this issue Jan 5, 2024 · 0 comments
Open

[chore] Restructure developer docs #855

andrewnicols opened this issue Jan 5, 2024 · 0 comments
Labels
help wanted Extra attention is needed needs-triage repo

Comments

@andrewnicols
Copy link
Member

What do we need to do?

When we started the devdocs we tried to consider to structure our existing content better.

We have, largely speaking, achieved that. However, the current structure is still somewhat confusing.

flowchart TD
    C[Versioned documentation]
    C --> GUIDES[Developer Guides]
    C --> API[API Guides]
    API --> FILES[Common files]
    API --> CORE[Core APIs]
    API --> PLUGIN[Plugin Types]
    API --> SUBSYSTEM[Subsystems]
    C --> DEVUP[Developer Updates]
Loading

Within each of API guide sections we have a fairly large list of APIs and information, and it isn't always clear which location docs should be in. For example, the Output API documentation which covers critical methods such as {{format_string}}, and {{format_text}} are under Subsystems, but arguably these shoudl be uder "Core APIs". For most people APIs such as these subsystem APIs are so critical to the daily development of Moodle that their categorisation as a subsystem is confusing when compared to a subsystem such as Task, Editor, Privacy, Check, Availability, etc.

I think we need to find a way to reduce these restructure some of these categories, and perhaps toimprove our "Developer guides" too.

Many of the se Core API and Subsystem docs would be better served as guides. It is not in our interest to store API documentation in any static form with function signatures in these docs. We should find better ways to link to the live documentation instead.

@andrewnicols andrewnicols added help wanted Extra attention is needed repo labels Jan 5, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
help wanted Extra attention is needed needs-triage repo
Projects
None yet
Development

No branches or pull requests

1 participant