Getting started - Organization and brief info #174
Conversation
This file contains hidden or 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
Kelvinrr
reviewed
Sep 30, 2025
Comment on lines
+111
to
+119
| ??? info "Contributing/Writing *Getting Started* Pages" | ||
|
|
||
| Getting Started tutorials are lessons. Readers should be given a reasonable starting point, and should able to follow the tutorials with no external guidance. They are learning-oriented documents designed with the purpose of enabling new users to get started with a particular part of the software portfolio. | ||
|
|
||
| When creating a new getting-started tutorial, first you need to make sure what you are creating is a tutorial. Ask yourself: | ||
|
|
||
| When creating a new getting-started tutorial, first you need to make sure what you are creating is a tutorial. Ask yourself: | ||
| * What is the lesson? Tutorials should have a lesson that the user is expected to learn. | ||
| * Does your tutorial have a concrete beginning? Tutorials should always have an obvious start with clear instructions on how to get any lesson examples running. | ||
| * Does your tutorial have a goal? Tutorials should have a clear goal that the user will accomplish. |
There was a problem hiding this comment.
I think it's better to put this at the top
There was a problem hiding this comment.
I can put it at the top if you want, but I have a couple of reasons to consider leaving it at the bottom.
- My goal is to put the thing people are most likely looking for closest to the top.
- People on the Getting Started page may not be the most knowledgeable about our software yet, contributing is a great end but probably not what people want to start with.
This might be a better way to encourage editing: adding an edit/view source button in the header/footer of each page. This is what wikipedia and many docs sites I've seen do. mkdocs-material has a feature that makes this pretty easy to add: https://squidfunk.github.io/mkdocs-material/setup/adding-a-git-repository/
There was a problem hiding this comment.
PR with mkdocs git features, was really easy to add.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
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.
Licensing
This project is mostly composed of free and unencumbered software released into the public domain, and we are unlikely to accept contributions that are not also released into the public domain. Somewhere near the top of each file should have these words: