diff --git a/docs/documentation-modes.rst b/docs/documentation-modes.rst deleted file mode 100644 index a232267056..0000000000 --- a/docs/documentation-modes.rst +++ /dev/null @@ -1,71 +0,0 @@ -Documentation in four modes of information delivery -=================================================== - -.. rst-class:: intro -Wagtail documentation is written in four modes of information delivery. -Each type of information delivery has a purpose and targets a specific audience. - - * :ref:`doc-style-tutorial`, learning-oriented - * :ref:`doc-style-how-to-guide`, goal-oriented - * :ref:`doc-style-reference`, information-oriented - * :ref:`doc-style-explanation`, understanding-oriented - -Credits `Daniele Procida: What nobody tells you about documentation `__. - -Write in style --------------- - -Each page of the Wagtail documentation should be written in **one** mode of information delivery. - -Mixing types of information delivery on a single page is bad style. -These pages are are confusing to read, and harder to understand. -It is best to split documents that mix the types of information delivery. -Add links to the first section of each document to cross reference the same topic. - -Writing documentation in a specific mode will help our users to understand, and quickly find what they are looking for. - -.. _doc-style-tutorial: - -Tutorial --------- - -Tutorials are designed to be a **learning-oriented** resource that take -newcomers by the hand and guide them through a specific topic. To facilitate effective -learning, tutorials provide examples to illustrate the subjects they cover. - -They may not necessarily follow best-practices by the letter. They are -designed to make it easier to get started. - -`More about tutorials `__ - - -.. _doc-style-how-to-guide: - -How-to guide ------------- - -A guide offer advice on how best to achieve a given task. How-to guides are **goal-oriented**. - -`More about how-to guides `__ - - -.. _doc-style-reference: - -Reference ---------- - -A reference is well structured and allows the reader to find information about a specific -topic. They should be short and to the point. Reference material is **information-oriented**. - -`More about reference `__ - - -.. _doc-style-explanation: - -Explanation ------------ - -Explanation is high-level and explains concepts and design decisions. -There little, or no code involved. Background information is **understanding-oriented**. - -`More about explanation `__ diff --git a/docs/index.rst b/docs/index.rst index f6730cc1e8..9727ab04c1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -43,4 +43,3 @@ Index editor_manual/index contributing/index releases/index - documentation-modes \ No newline at end of file