feat(markdown): Docs on docs structure
This commit is contained in:
parent
149ad90feb
commit
14096f56df
7 changed files with 517 additions and 5 deletions
44
markdown/dev/guides/docs/en.md
Normal file
44
markdown/dev/guides/docs/en.md
Normal file
|
@ -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:
|
||||
|
||||

|
||||
|
||||
|
||||
- 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
|
||||
|
||||
|
||||
<Note>
|
||||
|
||||
##### 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.
|
||||
|
||||
</Note>
|
||||
|
Loading…
Add table
Add a link
Reference in a new issue