diff --git a/markdown/dev/guides/docs/docs.png b/markdown/dev/guides/docs/docs.png new file mode 100644 index 00000000000..64c9301b786 Binary files /dev/null and b/markdown/dev/guides/docs/docs.png differ diff --git a/markdown/dev/guides/docs/docs.svg b/markdown/dev/guides/docs/docs.svg new file mode 100644 index 00000000000..eba14ae904f --- /dev/null +++ b/markdown/dev/guides/docs/docs.svg @@ -0,0 +1,404 @@ + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + Guides + Howtos + Reference + Tutorials + + + discovering + learning + working + double-checking + Discord & Githbub + + I want to learn about... + I want to learn about... + + + I want to do this common thing + I want to do this common thing... + + + What even is this thing??? + What even is this thing??? + + + What was that parameter again... + What was that parameter again... + + + I'm stuck; Help! + I'm stuck; Help! + + + diff --git a/markdown/dev/guides/docs/en.md b/markdown/dev/guides/docs/en.md new file mode 100644 index 00000000000..f4090560c0c --- /dev/null +++ b/markdown/dev/guides/docs/en.md @@ -0,0 +1,44 @@ +--- +title: How we structure our documentation +--- + +Whether you're writing documenation for FreeSewing, or merely trying +to find what you are looking for, understanding how we structure our +documentation can help you find your feet, and figure out what goes where. + +## Types of documentation + +Our documentation is divided into four different types: + + - [**Tutorials**](/tutorials) are lessons that lead you through a series of steps to complete a project. + - [**Guides**](/guides) tell a story to further your understanding of a specific topic. + - [**Howtos**](/howtos) give you concrete steps to solve a common problem or challenge. + - [**Reference**](/reference) holds technical descriptions of the underlying technology and how to make use of it. + +Each time you write documentation, you have to ask yourself: Is it a tutorial? Is it a Guide? +Is it a Howto? Or is it Reference documentation. + +If you find it hard to answer that question, the illustration below might help you figure out +where your documentation should go based on what it's trying to accomplish: + +![A graphic showing a visual representation of our documentation +structure](docs.png "A visual representation of how our documentation is structured") + + +- Write a **Tutorial** is your aim is to help people learn the platform +- Write a **Guide** if your aim is to further people's understanding of a topic by going a bit deeper +- Write a **Howto** if your ain is to help people accomplish a task +- Write **Reference** documentation to detail how things work under the hood +- Refer people to **Discord or Github** for things that are not (yet) covered in our documentation + + + + +##### Based on a talk by Daniele Procida + +This structure is loosely based +on [this talk by Daniele Procida](https://www.youtube.com/watch?v=t4vKPhjcMZg) at +PyCon AU 2017. + + + diff --git a/markdown/dev/guides/en.md b/markdown/dev/guides/en.md index 8994a5bd5fb..1f7819e91bc 100644 --- a/markdown/dev/guides/en.md +++ b/markdown/dev/guides/en.md @@ -1,5 +1,23 @@ --- title: Guides -order: 1020 +order: zbb --- +You can find a list of all FreeSewing guides below: + + + + + + +##### What makes a guide a guide? + +Guides tell a story to further your understanding of a specific topic. + +Guides and howtos are on a spectrum with howtos being terse *do-this-then-that* recipes, whereas +guides take more time to explain in-depth what is being done and why. + +For more details, refer to [How we structure our documentation](/guides/docs). + + + diff --git a/markdown/dev/howtos/en.md b/markdown/dev/howtos/en.md index 82361b22d97..876815b5dd2 100644 --- a/markdown/dev/howtos/en.md +++ b/markdown/dev/howtos/en.md @@ -1,5 +1,23 @@ --- title: Howtos -order: 1020 +order: zcc --- +You can find a list of all FreeSewing hotwtos below: + + + + + + +##### What makes a howto a howto? + +Howtos give your concrete steps to solve a common problem or challenge. + +Guides and howtos are on a spectrum with howtos being terse *do-this-then-that* recipes, whereas +guides take more time to explain in-depth what is being done and why. + +For more details, refer to [How we structure our documentation](/guides/docs). + + + diff --git a/markdown/dev/reference/en.md b/markdown/dev/reference/en.md index ddffb071d6b..b102d482519 100644 --- a/markdown/dev/reference/en.md +++ b/markdown/dev/reference/en.md @@ -1,7 +1,20 @@ --- title: Reference -order: 1040 +order: zdd --- - +You can find a list of all FreeSewing reference documentation below: + + + + + + +##### What makes a guide a guide? + +Reference materials hold technical descriptions of the underlying technology and how to make use of it. + +For more details, refer to [How we structure our documentation](/guides/docs). + + diff --git a/markdown/dev/tutorials/en.md b/markdown/dev/tutorials/en.md index 74a5ae90619..c0880c4bcae 100644 --- a/markdown/dev/tutorials/en.md +++ b/markdown/dev/tutorials/en.md @@ -1,5 +1,20 @@ --- title: Tutorials -order: 1010 +order: zaa --- +You can find a list of all FreeSewing tutorials below: + + + + + + +##### What makes a tutorial a tutorial? + +Tutorials are lessons that take you by the hand through a series of steps to complete a project. + +For more details, refer to [How we structure our documentation](/guides/docs). + + +