Reorganise introductory docs #520
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
penelopeysm
requested review from
yebai and
mhauru
and removed request for
yebai
|
Preview the changes: https://turinglang.org/docs/pr-previews/520 |
The excised material is more appropriate for the very first page that people click on.
1. Remove the section on posterior checks; this is the landing page and it's not necessary for people reading about the library for the first time to go through that. 2. Signpost the way to the rest of the documentation at the bottom. 3. Minor wording changes
penelopeysm
force-pushed
the
pysm/getting-started
branch
from
e470fde to
4f238d1
Compare
|
(Rebased on master.) |
|
It looks fairly sensible to me to structure the docs for different audiences, i.e. Users and Developers. @penelopeysm, can you start a new docs page, "Frequently Asked Questions (FAQs)," under "Users"? |
yebai
approved these changes
Sep 11, 2024
yebai
reviewed
Sep 11, 2024
mhauru
reviewed
Sep 12, 2024
Co-authored-by: Hong Ge <[email protected]>
|
@yebai Re. FAQ, sure! I'll add that to the docs roadmap, for another PR. |
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 streamlines the various 'introductions' docs that we have.
Collectively, the aim is to present a more coherent structure to visitors and to clarify the order in which they should read the docs.
Specifically, I:
updated the sidebar headings to more descriptive names.
separated out the 'Getting Started' and 'Guide' (renamed to 'Core Functionality') pages from the first section because these are the docs that you basically want every user to read, whereas everything else in that section is more like "I'll pick it up as and when I need it".
streamlined the 'Getting Started' page. I removed the section on analytical posterior because this is not really material that a first-time user needs to read, it's covered in the tutorial sections. In its place I add a paragraph that signposts the rest of the docs.
removed the 'Quick Start' page as it serves the same purpose as the Getting Started page (i.e. a short and sweet example of defining and running a model), and we don't need two of them.
removed duplicated material from the 'Introduction to Turing' tutorial. For example the discussion on prerequisite knowledge has been moved to the Getting Started page instead, because that's where people are most likely to be reading it.
I have more plans for work on the docs :), but I don't want to make too many changes without asking for some review.