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.

Sign up for GitHub

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

Jump to bottom

Docs overhaul for Transportation theme #14

Merged
merged 7 commits into from
Aug 21, 2023
Merged

Docs overhaul for Transportation theme #14

merged 7 commits into from
Aug 21, 2023

Conversation

vcschapp
Copy link
Collaborator

@vcschapp vcschapp commented Jun 19, 2023 •
edited
Loading

Description

This PR updates the theme-level Transportation documentation in the Docusaurus website to be more complete, more detailed, while hopefully telling a more approachable story.

  • New page Shape and Connectivity tries to capture the "network" and "segmentation" aspects of the Transportation story without getting bogged down into things like LR and scoped properties.
  • New page Scoped and Rule-Based Properties tries to explain how scoping and rules work, starting from the beginning and giving examples.
  • New page Roads tries to hit the main concepts involved in road segments.
  • New page Travel Modes tries to explain travel modes. Within this process, I try to address the concerns addressed in Schema Discussion OvertureMaps/schema-wg#17 about how to know which of using, recognized, or mode/modeNot to use in a given circumstance.

The overall transportation theme index page is also updated with new text, and treated as more of an introduction linking out to sub-pages for detailed explanations.

Testing

  1. The live version of the changes in this PR are built to https://dfhx9f55j8eg5.cloudfront.net/pr/14/themes/transportation/.
  2. Hyperlinks.
    1. Inter-page hyperlinks are tested as part of the build process.
    2. I have tested the intra-page anchor links (#links) and out-of-website links to OSM to the best of my ability.
  3. Fluid layout. I have made use of a lot of CSS features, mostly to create two-column or multi-column layouts. I've done my best to test these "manually".

Callouts

  • The graphics do not display well in 🌒 Dark Mode. I think this is OK temporarily: Linux Foundation has folks who volunteered to redo my diagrams using the Overture color palette, so hopefully we can ask them to produce a Dark Mode version of each picture and we can then insert them using the Docusaurus theme-styled images feature. IMO this shouldn't block merging and giving users better documentation sooner.
  • I have made use of a lot of CSS features, mostly to create two-column or multi-column layouts. I'm not an expert in HTML/CSS wizardry so I would appreciate it:
    • If you have some kind of expertise, would you mind looking at the markup/CSS from that standpoint?
    • If not, would you mind testing the rendering in different viewport sizes and/or different browsers and just looking for glaring issues?

@vcschapp vcschapp force-pushed the transportation_better_docs branch 3 times, most recently from 18ed7b2 to 86c5e22 Compare June 21, 2023 22:35
@vcschapp
Copy link
Collaborator Author

Roads page is finally done. Travel modes is the last one up.

@vcschapp vcschapp force-pushed the transportation_better_docs branch 2 times, most recently from 16a28e4 to 49510fc Compare June 23, 2023 20:48
@vcschapp
Write thorough docs for Scoped Properties
042d32a 
Most of the work is done on the `scoping-rules.mdx` page, but note that
some stuff is either (a) commented out; or (b) inaccurate because of
detects I found and documented while writing up this page. Here are
some of the problems:

- Lanes model: https://github.com/OvertureMaps/schema-wg/issues/148
- General issues: https://github.com/OvertureMaps/schema-wg/issues/147
- Environmental: OvertureMaps/schema-wg#146
- Flags: OvertureMaps/schema-wg#144
@vcschapp
Add a short status section for Transportation theme docs
43279ae
@vcschapp
Write thorough docs for Roads
729366b
@vcschapp vcschapp force-pushed the transportation_better_docs branch 2 times, most recently from 1392e08 to a902483 Compare June 23, 2023 20:57
@vcschapp
Copy link
Collaborator Author

PR is 100% complete, all pages are ready for review.

@larryfreil larryfreil self-requested a review June 26, 2023 22:01
Base automatically changed from dev to main July 12, 2023 15:23
@vcschapp
Copy link
Collaborator Author

Having finished the combobulator updates, I'm planning to come back to this tomorrow or Friday, with a goal of having a shippable update by mid-week next week.

In addition to Larry, Sanjib, and Ola's feedback on this PR, I have a list of update points and suggestions from Rob S. to work in....

@mtmail
Copy link

mtmail commented Aug 16, 2023

The https://github.com/OvertureMaps/schema-wg/ repository seems to be set to private.

@vcschapp
Copy link
Collaborator Author

The https://github.com/OvertureMaps/schema-wg/ repository seems to be set to private.

Yes that's correct. Overture's still maturing as an organization and we are still working out how some of our process will work. I believe the plan is to change this at some point in the future as our process gets more formalized...

@vcschapp
Improve shape/connectivity docs based on Rob S. feedback
e922733 
This commit is based on a feedback email to me from
[email protected]. Thanks Rob!
vcschapp added a commit that referenced this pull request Aug 18, 2023
@vcschapp
Improve transportation docs based on PR#14 feedback
b6af8fb 
This commit incorporates changes suggested or implied by Ola and Larry
on the PR: #14.
larryfreil
larryfreil approved these changes Aug 19, 2023
View reviewed changes
Copy link
Contributor

@larryfreil larryfreil left a comment

Choose a reason for hiding this comment

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

I have one question around implied restrictions that I think is particularly unclear with a proposed change depending on what restrictions are implied.

Also, we may want to as future work create guidelines around examples as there are at least 3 different ways we have represented coordinates, namely:
coordinates: [[0, 0], [1, 1]] #TODO get some real geometry
--OR--
coordinates:
- [-123.13174398677468, 49.28492173297815]
- [-123.13015725772073, 49.283923094445726]
--OR--
coordinates:
- - -123.12244656918179
- 49.280940587393815
- - -123.12562968007902
- 49.27884862879665

Its a minor point, but I did find it jarring for side-by-side examples that I think distract from the actual difference the examples are trying to illustrate.

docusaurus/docs/themes/transportation/roads.mdx Show resolved Hide resolved
@vcschapp
Copy link
Collaborator Author

I have one question around implied restrictions that I think is particularly unclear with a proposed change depending on what restrictions are implied.

Also, we may want to as future work create guidelines around examples as there are at least 3 different ways we have represented coordinates, namely: coordinates: [[0, 0], [1, 1]] #TODO get some real geometry --OR-- coordinates: - [-123.13174398677468, 49.28492173297815] - [-123.13015725772073, 49.283923094445726] --OR-- coordinates: - - -123.12244656918179 - 49.280940587393815 - - -123.12562968007902 - 49.27884862879665

Its a minor point, but I did find it jarring for side-by-side examples that I think distract from the actual difference the examples are trying to illustrate.

This is something I think we should address as an overarching schema TF issue relating to docs quality and documentation strategy. I'll cut an issue.

vcschapp added a commit that referenced this pull request Aug 21, 2023
@vcschapp
Improve transportation docs based on PR#14 feedback
0731c60 
This commit incorporates changes suggested or implied by Ola, Larry,
and Sanjib on the PR: #14.
@vcschapp
Improve transportation docs based on PR#14 feedback
48a2a89 
This commit incorporates changes suggested or implied by Ola, Larry,
and Sanjib on the PR: #14.
@vcschapp
Copy link
Collaborator Author

Merging it. Woooooo! 🎉

@vcschapp vcschapp merged commit 040b2cc into main Aug 21, 2023
2 checks passed
@vcschapp vcschapp deleted the transportation_better_docs branch August 21, 2023 23:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@AleksandraDebicka-TomTom AleksandraDebicka-TomTom AleksandraDebicka-TomTom left review comments

@larryfreil larryfreil larryfreil approved these changes

@sanjibdutta1 sanjibdutta1 sanjibdutta1 approved these changes

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
5 participants
@vcschapp @mtmail @larryfreil @AleksandraDebicka-TomTom @sanjibdutta1