docs: guides overhaul #128
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This PR is a complete overhaul of the `guides/` directory. While trying to wrap my head around the library, I found the existing Guides to be a bit confusing and lacking. Using the existing Guides as a starting point, I have re-structured and added a lot of new content to make the Guides more useful and easier to navigate. I also paid attention to the style and formatting to make it easier to read and understand, while sticking to the existing style as much as possible. This is _my_ understanding of the library, which I pieced together from the existing Guides, examples, API Docs and delving into the `src/` and `development/` source code. Props to TypeScript for helping out with the latter. I am sure there are some errors and omissions, so feedback welcome and I am happy to make any changes as needed. ## Changes In this new form, the `guides/` directory contains the following Markdown pages: 1. Getting Started 2. Adapters 3. Modes 4. Styling 5. Events 6. Development ### Restructuring / Navigation - All pages in the `guides/` directory now have a numeric prefix to control the order in which they appear. The exception is the `CODE_OF_CONDUCT.md` file, which I have left as-is. - At the end of each page there is a list of links to the other pages in the `guides/` directory, so it is easy to navigate between them. ### 1.Getting Started - Added additional Key Concepts content: - Store - Adapters - Modes - Improved Installation instructions. ### 2.Adapters Added sections: - Available Adapters - Using Adapters - Examples: - Leaflet - MapLibre - Google Maps - MapBox ### 3.Modes Added sections: - Mode Names - Drawing Modes - Selection Mode - Render Mode - Adding Modes - Enabling Modes - Loading Features ### 4.Styling Added sections: - Drawing Modes: - Points - Lines - Polygons - Freehand - Great Circle - Circle - Rectangle - Selection Mode - Points - Lines - Polygons - Selection Points - Mid Points - Render Mode - Points - Lines - Polygons ### 5.Events Restructured sections into: - Native Events - Terra Draw Events ### 6.Development Mostly minor tweaks and improvements. ### General / Other - Added inline Alerts to highlight important information. - Added lang to all code blocks. - Lots of minor tweaks to improve formatting and readability. ### Removed - `guides/COMMON_PATTERNS.md` - content broken up and moved to other pages. - `guides/CONTRIBUTING.md` - content moved to `DEVELOPMENT.md#contributing`. The README.md file in the root directory, as well as the `docs/index.html` has been updated to reflect these Guide location changes.
|
@morehawes thanks for this, appreciate your hard work here. I'm just away for the weekend but will get to looking at this next week with some thoughts! |
|
Hey @morehawes I've not forgotten about this just been really busy in the run up to Christmas with work. I just think the docs are really important and want to get them right! I'll get to this soon over the holidays 👍🏻 Thanks again for your input! |
|
@JamesLMilner, Sounds good, enjoy the holidays :) |
You're welcome and I have made the changes you suggested :) |
|
Thanks @morehawes, appreciate your hard work on this. Hopefully people find this easier to follow now! |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR is a complete overhaul of the
guides/directory. While trying to wrap my head around the library, I found the existing Guides to be a bit confusing and lacking.Using the existing Guides as a starting point, I have re-structured and added a lot of new content to make the Guides more useful and easier to navigate. I also paid attention to the style and formatting to make it easier to read and understand, while sticking to the existing style as much as possible.
This is my understanding of the library, which I pieced together from the existing Guides, examples, API Docs and delving into the
src/anddevelopment/source code. Props to TypeScript for helping out with the latter.I am sure there are some errors and omissions, so feedback welcome and I am happy to make any changes as needed.
Changes
In this new form, the
guides/directory contains the following Markdown pages:Restructuring / Navigation
guides/directory now have a numeric prefix to control the order in which they appear. The exception is theCODE_OF_CONDUCT.mdfile, which I have left as-is.guides/directory, so it is easy to navigate between them.1.Getting Started
2.Adapters
Added sections:
3.Modes
Added sections:
4.Styling
Added sections:
5.Events
Restructured sections into:
6.Development
Mostly minor tweaks and improvements.
General / Other
Removed
guides/COMMON_PATTERNS.md- content broken up and moved to other pages.guides/CONTRIBUTING.md- content moved toDEVELOPMENT.md#contributing.The README.md file in the root directory, as well as the
docs/index.htmlhas been updated to reflect these Guide location changes.