Skip to content

Empty overview doc pages with missing links to subtopics #87

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

Open
Wryhder opened this issue May 11, 2024 · 9 comments · May be fixed by #135
Open

Empty overview doc pages with missing links to subtopics #87

Wryhder opened this issue May 11, 2024 · 9 comments · May be fixed by #135

Comments

@Wryhder
Copy link

Wryhder commented May 11, 2024

Expected behaviour: Clicking on a high-level topic or a label used to organize related subtopics should open an overview page with some content (e.g, Fundamentals > Asterisk Architecture) or load the first sub-item (e.g, Getting Started > Beginning Asterisk).

Actual behaviour: There are several empty overview pages.

empty page missing links to subtopics-fundamentals

Based on pages like the one below, the docs are being developed. I'd still like to suggest including links to the sub-topics or sub-items on the overview page (in addition to the under construction warning) pending when the overview content is created.

empty page missing links to subtopics-fundamentals-key concepts

TODO: Update issue with links to all empty overview pages.

@gtjoseph
Copy link
Member

The page for Asterisk Architecture does have content...
image

Adding links to sub-topics in the overview content pages is tricky because the navigation is generated dynamically by mkdocs. I'll see if there's some way we can handle it.

@Wryhder
Copy link
Author

Wryhder commented May 13, 2024

The page for Asterisk Architecture does have content... image

Yes, I included this as an example of an overview page with some content. I suppose I didn't express that clearly.

Adding links to sub-topics in the overview content pages is tricky because the navigation is generated dynamically by mkdocs. I'll see if there's some way we can handle it.

What should go into the overview docs? Will a summary of the ideas in the subsections suffice (with relevant links to each subsection within the overview text, along with footer links to the previous and next page of the current page)?

@Wryhder Wryhder changed the title Empty doc pages with missing links to subtopics Empty overview doc pages with missing links to subtopics May 13, 2024
@Wryhder
Copy link
Author

Wryhder commented May 22, 2024

What should go into the overview docs? Will a summary of the ideas in the subsections suffice (with relevant links to each subsection within the overview text, along with footer links to the previous and next page of the current page)?

@gtjoseph Hi! I wanted to ask if you'll be creating the overview pages in-house, or could I work on it?

@gtjoseph
Copy link
Member

@Wryhder Sorry for the delay. If you still want to work on it, why don't you create one or two as an example so we can see what you have in mind and submit a PR. We can go from there.

@ipaqmaster
Copy link

Trying to use this documentation has been a pretty frustrating experience to say the least. Most of the pages just say under construction and have blank content. Where's the actual documentation?

@Wryhder
Copy link
Author

Wryhder commented Apr 4, 2025

@gtjoseph Apologies. I'd missed your previous response. I'll look into creating an example and get back to you within the next few weeks.

@Wryhder
Copy link
Author

Wryhder commented Apr 4, 2025

@ipaqmaster I can't take a look right now, but wasn't it mostly the overview pages that have missing content?

If you use the left sidebar navigation and expand the link categories with the arrows, there's a lot of existing documentation. Unless there's something specific not covered?

(Not sure where you can get a faster response from the team.)

@ipaqmaster
Copy link

ipaqmaster commented Apr 4, 2025

Yes just the top levels though I got myself set up a little easier with the sample configuration. I expected the official documentation to be more helpful. Or perhaps just more complete.

@gtjoseph
Copy link
Member

gtjoseph commented Apr 5, 2025

@ipaqmaster Give me some examples of where it could be more helpful. There's tons of documentation but the category pages are sparsely populated so if you're not using the left navigation bar you might not see it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
3 participants