{"_id":"5703c7f2903e330e002d871f","category":{"_id":"5703c7f2903e330e002d870c","version":"5703c7f2903e330e002d8703","__v":0,"project":"56682f6c1fb5701900f893a0","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-04-05T10:54:33.977Z","from_sync":false,"order":9,"slug":"documentation-guides","title":"Documentation guides"},"version":{"_id":"5703c7f2903e330e002d8703","__v":4,"hasDoc":true,"hasReference":true,"project":"56682f6c1fb5701900f893a0","createdAt":"2016-04-05T14:13:06.422Z","releaseDate":"2016-04-05T14:13:06.422Z","categories":["5703c7f2903e330e002d8704","5703c7f2903e330e002d8705","5703c7f2903e330e002d8706","5703c7f2903e330e002d8707","5703c7f2903e330e002d8708","5703c7f2903e330e002d8709","5703c7f2903e330e002d870a","5703c7f2903e330e002d870b","5703c7f2903e330e002d870c","573d96148ca48f320093ed5b","573dd2e38cf1492400bba6e0","57a9cc1f5b1ace0e00de743e"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"2.0.0","version":"2"},"project":"56682f6c1fb5701900f893a0","user":"56684a10ee1dbf0d008f621d","__v":2,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-04-05T10:55:30.063Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"## Types of document\n\nWe have three types of user docs:\n\n1. **Tutorials** - to show users all of the steps required to complete a task and explain the reasons behind those steps\n1. **Reference** - to share everything we know about a particular feature or widget\n1. **Help** - to get users 'unstuck' when they encounter common problems\n\nTutorials can become quite long and may need to be broken into several parts to keep the document length manageable. We will sometimes make tutorials as videos but we will still need the document for our partners who need something easily translatable. \n\nReference documents are the easiest kind to write but may be the least useful for a user. Most users don't want to know everything about a widget, they just want to know the one thing that will solve their problem. \n\n## Document management\n\nWe are using a tool called Readme (www.readme.io) to manage the creation and publishing of all V8 user documentation. In the past, we've used Zendesk and all V6 / V7 docs will remain on Zendesk.\n\nWe have two 'Projects' on Readme.io: \n\n1. resources.basekit.com - for all partner facing documentation\n2. sitebuilder.readme.io - for all user facing documentation\n\nWe're using Readme because it makes updating documents very easy and can be  used by anyone inside or outside of BaseKit. \n\nReadme uses a variation of Markdown for text formatting. \n\nWith Markdown, you use simple keystrokes to indicate formatting for a webpage instead of typing it as HTML. \n\nExamples:\n\n* \\# The largest heading\n* \\## The second largest heading\n* You can make a list by preceding one or more lines of text with - or *.\n* \\** bold text \\** will be rendered as **bold text**\n\nYou'll need to take a few minutes to learn about [Markdown](https://help.github.com/articles/basic-writing-and-formatting-syntax/) before using Readme. \n\nReadme also supports the use of icons (from Font Awesome) and emoji.\n\n**Limitations of readme.io**\n\nThe main limitation of Readme is that it has only level of categorisation so we can't created nested structures like **English / Sitebuilder / Getting started**. We need to support many languages but readme project cost about $60/month so we can't afford to have one for each language.  Readme claim they will fix this in a future release but for now  the only way to create a categorised list of docs is to create a 'custom' page i.e. a page that has links to all our docs arranged in some sensible way. Here's an [example](https://sitebuilder.readme.io/v1.0/page/english-user-document) page.\n\n\n\n## Language\n\nOur English documentation will be often be used by people who do not speak English as a first language. \n\nTo aid comprehension, we should try to avoid:\n\n* Figures of speech\n  * \"Shoot an email over to our support team\"\n* Contractions\n  * \"don't\", \"hasn't\"\n* Abbreviations\n  * \"TDK\"\n* Internal language\n  * \"Desktop\", \"Package\"\n\nThere maybe exception cases for any of these but unless you're certain you have an exception case you should avoid them. \n\n## Tips for creating screenshots\n\n1. Capture at a consistent window size (say 1280 x 900). To set this easily, use a Chrome plugin like [resolution test](https://chrome.google.com/webstore/detail/resolution-test/idhfcdbheobinplaamokffboaccidbal?hl=en)\n2. Hide your browsers bookmarks bar (Shift-CMD-B) and any visible plugin icons\n3. Learn the keyboard shortcuts for capturing windows and parts of windows ([https://support.apple.com/en-gb/HT201361)](https://support.apple.com/en-gb/HT201361) \n4. To save your screenshot to the Clipboard instead of a file on your desktop, use Command-Shift-Control-4.\n\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/iPBDP9WIR0eAqNiaK8hT_tips-for-creating-screenshots.jpg\",\n        \"tips-for-creating-screenshots.jpg\",\n        \"1294\",\n        \"922\",\n        \"#1372c7\",\n        \"\"\n      ],\n      \"caption\": \"Creating a bad screenshot\"\n    }\n  ]\n}\n[/block]\n## Using animations\n\nAnimations are a really good way to show the user how to interact with a piece of UI, as well as showing what the reactions might be from using it. Here are a few tips:\n\n- Use [LICEcap](http://www.cockos.com/licecap/) or [Git Brewery](http://gifbrewery.com/) to record animations, others are available\n- Make sure to crop in with animations as the cursor is hard to recognise\n- Try and keep under the size of 960px square, either by cropping the image or by scaling down your browser to show only the interaction mentioned\n- Use 24 frames per second as a default, but if the file size goes beyond what's recommend try a lower number\n- Crop browser and toolbars out if you can, this will keep the file size down and will less likely confuse the user\n- Make sure the gif is no larger than 950kb\n  - If you need it to be larger, consider the graphics that are on the same page. Do they collectively balance out?\n\nTake a look at the example below, note that the image has been deliberately scaled up. This is for visibility, we don't need to consider quality that much as gif images have a limited colour gamut anyway.\n[block:image]\n{\n  \"images\": [\n    {\n      \"caption\": \"Example gif\",\n      \"image\": [\n        \"https://files.readme.io/t0PIMA3QS6iHXWjvsyJV_adding-map.gif\",\n        \"adding-map.gif\",\n        \"840\",\n        \"600\",\n        \"#046ccb\",\n        \"\"\n      ],\n      \"sizing\": \"full\"\n    }\n  ]\n}\n[/block]\n## Create an example site\n\nIt's a good idea to create a site especially for use in creating help docs. For a business name, you can use 'Beekay' and create variations like Beekay Bikes, Beekay Holidays etc. \n\nMake sure that: \n\n* Any images you use are free of copyright restrictions (use unsplash.com or similar)\n* The words 'BaseKit' is never visible (some partners won't use documents that refer to our brand)\n* Any text content is spell checked\n\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/rPwhJTkStSYOhtDEYix1_create-an-example-site.jpg\",\n        \"create-an-example-site.jpg\",\n        \"1294\",\n        \"914\",\n        \"#2475c2\",\n        \"\"\n      ],\n      \"caption\": \"An example of an 'example site'\"\n    }\n  ]\n}\n[/block]\n## Giving instructions\n\nWe often need to give the user clear instructions on how to carry out a sequence of events. Usually, this will mean we create an annotated screenshot and an ordered (\"numbered\") list of actions that match the annotations.\n\nFor instructions, it's usually best to lead with verb ('click','move','enter'):\n\n1. Click **Add Page / Folder**\n1. Click the **Folder Tab**\n1. Enter a name for your folder\n1. Click **Save**\n\nFormatting the UI label in bold is optional but can make the list easier to read\n\nUse unordered lists (\"bullet points\") for listing examples where there is no particular order. \n\n## Text callouts in Readme.io\n\nReadme supports four kinds of text callout:\n\n1. **Info** - additional information that the user might find valuable\n1. **Warning** - information about limitations or minor potential problems\n1. **Danger** - an action that will result in major loss of work or other serious consequences\n1. **Success** - confirm the completion of a sequence of events and suggest possible next steps\n\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/1PXQaDODStFCmrijVkX1_text-callouts-in-readmeio.png\",\n        \"text-callouts-in-readmeio.png\",\n        \"813\",\n        \"475\",\n        \"#dc554d\",\n        \"\"\n      ],\n      \"caption\": \"Callouts in Readme\"\n    }\n  ]\n}\n[/block]\n## Tools for annotating screenshots\n\nYou can use any tool you are familiar with for annotating screenshots. If you're not familiar with graphic design tools, you can use Preview, the Mac application that's part of OS X (ask Gordon for a lesson on this).  We don't need a high level of visual consistency across documents as long the annotations are always clear.","excerpt":"An overview of how to create user-facing documentation for BaseKit V8","slug":"user-documentation-guidelines","type":"basic","title":"User documentation guidelines"}

User documentation guidelines

An overview of how to create user-facing documentation for BaseKit V8

## Types of document We have three types of user docs: 1. **Tutorials** - to show users all of the steps required to complete a task and explain the reasons behind those steps 1. **Reference** - to share everything we know about a particular feature or widget 1. **Help** - to get users 'unstuck' when they encounter common problems Tutorials can become quite long and may need to be broken into several parts to keep the document length manageable. We will sometimes make tutorials as videos but we will still need the document for our partners who need something easily translatable. Reference documents are the easiest kind to write but may be the least useful for a user. Most users don't want to know everything about a widget, they just want to know the one thing that will solve their problem. ## Document management We are using a tool called Readme (www.readme.io) to manage the creation and publishing of all V8 user documentation. In the past, we've used Zendesk and all V6 / V7 docs will remain on Zendesk. We have two 'Projects' on Readme.io: 1. resources.basekit.com - for all partner facing documentation 2. sitebuilder.readme.io - for all user facing documentation We're using Readme because it makes updating documents very easy and can be used by anyone inside or outside of BaseKit. Readme uses a variation of Markdown for text formatting. With Markdown, you use simple keystrokes to indicate formatting for a webpage instead of typing it as HTML. Examples: * \# The largest heading * \## The second largest heading * You can make a list by preceding one or more lines of text with - or *. * \** bold text \** will be rendered as **bold text** You'll need to take a few minutes to learn about [Markdown](https://help.github.com/articles/basic-writing-and-formatting-syntax/) before using Readme. Readme also supports the use of icons (from Font Awesome) and emoji. **Limitations of readme.io** The main limitation of Readme is that it has only level of categorisation so we can't created nested structures like **English / Sitebuilder / Getting started**. We need to support many languages but readme project cost about $60/month so we can't afford to have one for each language. Readme claim they will fix this in a future release but for now the only way to create a categorised list of docs is to create a 'custom' page i.e. a page that has links to all our docs arranged in some sensible way. Here's an [example](https://sitebuilder.readme.io/v1.0/page/english-user-document) page. ## Language Our English documentation will be often be used by people who do not speak English as a first language. To aid comprehension, we should try to avoid: * Figures of speech * "Shoot an email over to our support team" * Contractions * "don't", "hasn't" * Abbreviations * "TDK" * Internal language * "Desktop", "Package" There maybe exception cases for any of these but unless you're certain you have an exception case you should avoid them. ## Tips for creating screenshots 1. Capture at a consistent window size (say 1280 x 900). To set this easily, use a Chrome plugin like [resolution test](https://chrome.google.com/webstore/detail/resolution-test/idhfcdbheobinplaamokffboaccidbal?hl=en) 2. Hide your browsers bookmarks bar (Shift-CMD-B) and any visible plugin icons 3. Learn the keyboard shortcuts for capturing windows and parts of windows ([https://support.apple.com/en-gb/HT201361)](https://support.apple.com/en-gb/HT201361) 4. To save your screenshot to the Clipboard instead of a file on your desktop, use Command-Shift-Control-4. [block:image] { "images": [ { "image": [ "https://files.readme.io/iPBDP9WIR0eAqNiaK8hT_tips-for-creating-screenshots.jpg", "tips-for-creating-screenshots.jpg", "1294", "922", "#1372c7", "" ], "caption": "Creating a bad screenshot" } ] } [/block] ## Using animations Animations are a really good way to show the user how to interact with a piece of UI, as well as showing what the reactions might be from using it. Here are a few tips: - Use [LICEcap](http://www.cockos.com/licecap/) or [Git Brewery](http://gifbrewery.com/) to record animations, others are available - Make sure to crop in with animations as the cursor is hard to recognise - Try and keep under the size of 960px square, either by cropping the image or by scaling down your browser to show only the interaction mentioned - Use 24 frames per second as a default, but if the file size goes beyond what's recommend try a lower number - Crop browser and toolbars out if you can, this will keep the file size down and will less likely confuse the user - Make sure the gif is no larger than 950kb - If you need it to be larger, consider the graphics that are on the same page. Do they collectively balance out? Take a look at the example below, note that the image has been deliberately scaled up. This is for visibility, we don't need to consider quality that much as gif images have a limited colour gamut anyway. [block:image] { "images": [ { "caption": "Example gif", "image": [ "https://files.readme.io/t0PIMA3QS6iHXWjvsyJV_adding-map.gif", "adding-map.gif", "840", "600", "#046ccb", "" ], "sizing": "full" } ] } [/block] ## Create an example site It's a good idea to create a site especially for use in creating help docs. For a business name, you can use 'Beekay' and create variations like Beekay Bikes, Beekay Holidays etc. Make sure that: * Any images you use are free of copyright restrictions (use unsplash.com or similar) * The words 'BaseKit' is never visible (some partners won't use documents that refer to our brand) * Any text content is spell checked [block:image] { "images": [ { "image": [ "https://files.readme.io/rPwhJTkStSYOhtDEYix1_create-an-example-site.jpg", "create-an-example-site.jpg", "1294", "914", "#2475c2", "" ], "caption": "An example of an 'example site'" } ] } [/block] ## Giving instructions We often need to give the user clear instructions on how to carry out a sequence of events. Usually, this will mean we create an annotated screenshot and an ordered ("numbered") list of actions that match the annotations. For instructions, it's usually best to lead with verb ('click','move','enter'): 1. Click **Add Page / Folder** 1. Click the **Folder Tab** 1. Enter a name for your folder 1. Click **Save** Formatting the UI label in bold is optional but can make the list easier to read Use unordered lists ("bullet points") for listing examples where there is no particular order. ## Text callouts in Readme.io Readme supports four kinds of text callout: 1. **Info** - additional information that the user might find valuable 1. **Warning** - information about limitations or minor potential problems 1. **Danger** - an action that will result in major loss of work or other serious consequences 1. **Success** - confirm the completion of a sequence of events and suggest possible next steps [block:image] { "images": [ { "image": [ "https://files.readme.io/1PXQaDODStFCmrijVkX1_text-callouts-in-readmeio.png", "text-callouts-in-readmeio.png", "813", "475", "#dc554d", "" ], "caption": "Callouts in Readme" } ] } [/block] ## Tools for annotating screenshots You can use any tool you are familiar with for annotating screenshots. If you're not familiar with graphic design tools, you can use Preview, the Mac application that's part of OS X (ask Gordon for a lesson on this). We don't need a high level of visual consistency across documents as long the annotations are always clear.