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

Restructure docs landing page and some docs ordering. #2463

Merged
merged 8 commits into from
Mar 24, 2024

Conversation

freakboy3742
Copy link
Member

@freakboy3742 freakboy3742 commented Mar 23, 2024

A counterproposal to #2455.

Revises the documentation ordering so that:

  • The "Diataxis grid" has been restored, but with more direct links to second-level documents
  • The major sections have been reordered so that "tutorial" and "reference" are the first two (reflecting that those are the two most common targets for people arriving at the docs page)
  • The subtitles of each section have been re-ordered to surface more important details (like API documentation) first
  • The screenshot on the homepage has been moved to the about page.
  • Some other sections have been moved around:
    • the backend guides have been moved from how-to to background (reflecting the fact that this is background details)
    • the topic guides have been moved to how-to (reflecting the fact that they're "how to do layout/data sources etc")
    • "contribution" now has a landing page of it's own
  • Community contact details have been moved to the background section

A preview rendering is available

I'm not sure how I feel about the loss of the graphic - it was nice and splashy, even if it did take up a lot of space. I've removed it here for demonstration purposes, but I think I'd be just as happy to restore it.

PR Checklist:

  • All new features have been tested
  • All new features have been documented
  • I have read the CONTRIBUTING.md file
  • I will abide by the code of conduct

@freakboy3742
Copy link
Member Author

/cc @rmartin16 @HalfWhitt since you both expressed an interest in this topic.

@rmartin16
Copy link
Member

I think this is great 💯 and definitely an improvement on #2455.

On the backend pages, it may be worthwhile to add (Linux) to the GTK page....as long as we're, e.g., annotating Windows for WinForms.

As for the graphic, I definitely liked it on the landing page. I'm always a bit dumbfounded when I come to a GUI-centric library and there aren't any or at least any easily findable graphics.

For perspective, this is what the landing page looks like for me:
image

@freakboy3742
Copy link
Member Author

Ok - based on that feedback, I'll close #2455 and move forward on this one.

I've restored the screenshot to the homepage.

I've also merged the background section on platforms into the API - I noticed we had both; mostly duplicating the content; and in the reference section, the content is indexed by OS, rather than backend API.

Lastly, I've filled in some missing detail on the roadmap. That started as me noticing the markup was off... and I got carried away :-)

@freakboy3742 freakboy3742 marked this pull request as ready for review March 24, 2024 01:07
Copy link
Member

@rmartin16 rmartin16 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

mostly minor notes.

docs/reference/platforms/iOS.rst Outdated Show resolved Hide resolved
docs/reference/platforms/android.rst Outdated Show resolved Hide resolved
docs/background/community.rst Outdated Show resolved Hide resolved
docs/background/project/roadmap.rst Outdated Show resolved Hide resolved
docs/index.rst Show resolved Hide resolved
@freakboy3742 freakboy3742 merged commit b9a83f8 into beeware:main Mar 24, 2024
34 checks passed
@freakboy3742 freakboy3742 deleted the docs-landing branch March 24, 2024 22:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants