d3c76d87.853738fe.js

(window.webpackJsonp=window.webpackJsonp||[]).push([[47],{113:function(e,t,n){"use strict";n.r(t),n.d(t,"frontMatter",(function(){return r})),n.d(t,"metadata",(function(){return s})),n.d(t,"rightToc",(function(){return l})),n.d(t,"default",(function(){return h}));var o=n(2),a=n(6),i=(n(0),n(130)),r={title:"Content hierarchy"},s={unversionedId:"__guidelines/content-hierarchy",id:"__guidelines/content-hierarchy",isDocsHomePage:!1,title:"Content hierarchy",description:"Documentation should follow a hierarchy, this is true both for the content and",source:"@site/docs/__guidelines/content-hierarchy.md",slug:"/__guidelines/content-hierarchy",permalink:"/docs/__guidelines/content-hierarchy",version:"current"},l=[{value:"Content",id:"content",children:[]},{value:"Titles",id:"titles",children:[]},{value:"Bad practices",id:"bad-practices",children:[]}],c={rightToc:l};function h(e){var t=e.components,n=Object(a.a)(e,["components"]);return Object(i.b)("wrapper",Object(o.a)({},c,n,{components:t,mdxType:"MDXLayout"}),Object(i.b)("p",null,"Documentation should follow a hierarchy, this is true both for the content and\nhow titles are organized. In most cases, you can refer to a template and reuse\nthe hierarchy exposed there. When you write a page that does not derive from a\ntemplate, please follow the guidelines exposed here."),Object(i.b)("h2",{id:"content"},"Content"),Object(i.b)("p",null,"When you need to show a command, please show it at the top of your page as much\nas possible. This will ensure that users can easily copy/paste code without\nhaving to scan the whole page."),Object(i.b)("p",null,"It is okay to be very descriptive and thorough, however not every detail should\nhave the same weight. If you are documenting a function with many arguments,\nplease start with the most common ones first, gradually defining the ones that\npeople are less likely to use."),Object(i.b)("h2",{id:"titles"},"Titles"),Object(i.b)("p",null,"Pages need to start with text, not a title. Titles should always follow the\nfollowing hierarchy:"),Object(i.b)("pre",null,Object(i.b)("code",Object(o.a)({parentName:"pre"},{className:"language-shell"}),"h1 (title) > h2 (##) > h3 (###) > h4 (####)\n")),Object(i.b)("p",null,"This will improve readability and SEO. Example:"),Object(i.b)("pre",null,Object(i.b)("code",Object(o.a)({parentName:"pre"},{className:"language-markdown"}),"## The first title should be H2\n\nThen there should be some text\n\n### Then further titles should be H3\n\nThen ideally some text. Subsequent titles can then be used\n\n#### For example H4\n\nor even\n\n##### For example H5\n\netc\n")),Object(i.b)("h2",{id:"bad-practices"},"Bad practices"),Object(i.b)("ul",null,Object(i.b)("li",{parentName:"ul"},"Repetitive subtitles"),Object(i.b)("li",{parentName:"ul"},"Too many Tip/Info/Warning. Please use maximum 1-2 per page.")))}h.isMDXComponent=!0}}]);