name: front class: middle center inverse # Help ## User Manual .footnote[Boxxd - An automation tool] --- ## Contents .pull-left[ __[Introduction](#Description)__ * [Description](#Description) / [Use example](#UseExample) / [Advantages](#Advantages1) * [Use cases](#UseCases) __[Getting started](#GettingStarted)__ * [Getting going](#GettingStarted) * [Extra tools](#ExtraTools) * [Tips](#Tips) / [Problems...](#Friction) __[Working](#Editing)__ * [Markdown](#Editing) / [Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Here-Cheatsheet) / [Keywords](#keywords) * [Git](#WorkingGit) / [Dropbox](#WorkingDropbox) / [Remote Server](#WorkingRemote) __[Value Domains](#ValueDomains)__ * [Descriptions](#ValueDesc1) __[Q and A](#FAQ)__ * [FAQ](#FAQ) ] .pull-right[ __[Container structure](#RootDir)__ * [Root directory](#RootDir) / [.help](#HelpDir) / [.wiring](#WiringDir) * [Archive](#ArchiveDir) * [Items](#ArchiveDir) * [Works](#ArchiveDir) * [Talk](#TalkDir) * [Sources](#TalkDir) __[Functions](#HomeFunction)__ * [Home page](#HomeFunction) * [Talk](#TalkFunction) / [Slideshow](#SlideshowFunction) * [Ideas](#IdeasFunction) * [Help](#HelpFunction) __[Under the bonnet](#FileNaming)__ * [Files, directorys](#FileNaming) / [Extensions](#FileExtensions) / [Tagging](#Tagging) * [Headers and Meta info](#Headers) * [Automation](#Automation) ] --- name: Description ## Introduction ### Description This tool, the _Boxxd_ is a collection of tools to help people and teams manage their projects, products, ventures: * It is a container, offering a structure where things such as files can be logically stored. * It has a [Home](#HomeFunction) function helping people to navigate. * It has a [Talk](#TalkFunction) function, where important presentations can be stored. * It has a [Slideshow](#SlideshowFunction) function which can be used on the go. * It has an internal [Help](#HelpFunction) system. It can be easily edited, be shared, be packaged for further use such as for automation. [An overview of Boxxd is available here](ecosystem/boxxd-overview.html) --- name:UseExample (Introduction II) ### How can it be used? __The Team__ * Jack, Jill and Bill are working as a team on a project together. * They have various ideas about the content, illustrations, etc. __Sharing__ * They decide to use the Boxxd as a container for all their ideas. * And that all the project assets i.e. files, are also kept there. * They decide to use Dropbox for sharing. * Now all three can modify the files, and they are all synced together. __Tools__ * Jack uses the slideshow function during team talks in a café. * Bill uses the _Home_ file for linking major things together, so that new team members can easily find their way through the structure. * The _Jotter_ is helpful to catch snippets of information and thoughts. __Extending__ * Later they decide to track changes by using a popular change tool such as _git_. --- name: Advantages1 (Introduction III) ### Use and advantages It has been developed so that... __Sharing__ * Knowledge can be easily shared. * Transparent: People can easily see what's in it. * Logical structure for keeping things together __Working__ * Be used offline. * It can be easily edited with a text editor. * It is device independent - work on a mac, pc, linux, tablet, mobile. __Presentations__ * Slideshows can be easily run on the go, offline. --- name: Advantages2 (Introduction IV) __Standards__ * Experts in a specific area such as marketing, or product management (so called Value Domains), have a formalised structure with which they can work with. * Texts are in plain text and use the Markdown markup language. __Catalyst__ * The structure acts as a catalyst on how to do things. __Change tracking__ * The whole structure can be managed with a version control software such as git, for sharing, synchronisation, backup. __Automation__ * The container can be given to other systems, so that the contents can be automatically processed. --- name: UseCases (Introduction V) ### Use cases _Idea Management_ When developing an idea, notes can be written in simple markdown files _Product Development_ All the necessary data for marketing, service, etc., can be packaged together. _Venture Development_ Role players can build the venture in the Boxxd. _Proposals_ The structure can be used to swap info between parties. --- name: GettingStarted ## Getting started The best way of getting started is: 1. Ask youself _Why_ you want to use the Boxxd. 2. Learn how to create files, with the header. 3. Learn the basics of Markdown in the files. 4. Learn how to use the slideshow function with the _Talk_ directory. 5. Discover in which _Works_ directory you will be saving your primary documents. 6. Look at the internal structure of the Home.html file. Make a copy of it in the _Archive_ directory and have a go at editing the contents. .red.bold[Have fun!] --- name: ExtraTools (Getting started II) ### Extra tools you might need * Print out a cheatsheet of Markdown commands so that you can refer to them when needed. * Print out the [ValueDomain list](#ValueDomains) * To see the markdown files nicely in your browser, install a markdown converter extension in your browser (make sure that the option "read URL" is selected). * You might find it useful to use an editor with Markdown functionality i.e. it shows the headings and formating in colour and it offers a preview function. --- name: Tips (Getting started III) ### Tips * You can ignore filling out the header in the beginning, but still try to keep it there. * Weigh up when you are writing a document if you can do it in Markdown instead using your preferred writing tool such as Word. * The same when doing a presentation. * Spend a couple of minutes learning the basics of Markdown - It will save you time later. --- name: Friction (Getting started IV) ### Problems and friction Some people do not like having to learn new things: They will always find 101 reasons why they should not do it. With Boxxd it is no different. Some of the topics that might come up are: * I need to write "nice" documents * Why change - everything is okay the way it is * It is tooooooooo complicated If you are project lead you might need to come up with a strategy of how to win the other team members over to using Boxxd. Some of the answers might be: * "Hey... within a couple of minutes you can present __YOUR__ work in the Home page. * "You can have your own page within the Home page" * "With time you will find things faster" * "You will have an advantage over colleagues" Make could have a go at making a game out of it and ask them for ways on how to make things easier. Have a prize for the best idea. --- name: Editing ## Working ### Plain text One of the basic concepts of the Boxxd is that a person should focus on writing, on being creative, and that the computer should do the boring work of making sure that margins are correct, that paragraphs are properly separated, that tables look good and... that the text can be used for different document types such as a web page, a presentation or a book. That is why, if possible all content files should be plain text, and to support formatting and structure, the Markdown syntax is used. ### The Markdown syntax Markdown is simple to learn and fast to use. It is possible to create headings, add images, create tables. A Cheetsheet to the [Markdown syntax is here](https://github.com/adam-p/markdown-here/wiki/Markdown-Here-Cheatsheet). Boxxd has several extra markdown formating rules: [Here are more Markdown syntax notes](cheatsheets/markdown-syntax.html). --- name: Keywords (Working II) ### Keywords Keywords can be integrated into your documents so that you can track ideas, fixes, notes, questions and todos. The following keywords will be showed highlighted in some editors. .pull-left[ ``` BUG: FIXME: HACK: IDEA: ``` ] .pull-right[ ``` NOTE: QUESTION: REVIEW: TODO: ``` ] --- name: WorkingGit (Working III) ### Git Git is a tool to track changes to files. It can save you hours of work when working in teams, especially when somebody accidentally deletes a file unnoticed. There is a lot of information online on how to install and use. To get you started: Create a new git repository, by going into the root directory of the project and do: .red[git init] To add the files to git you need to do: * Add the files using .red[git add *] * Then commit with .red[git commit -m "blabla"] where blabla is a message saying what you are doing. Now the files have been saved. After doing changes you can repeat the git add and commit commands to save your changes. Please refer to the git documentation for other commands. There are free [visual Git clients for Mac and Windows](https://www.sourcetreeapp.com). --- name: WorkingDropbox (Working IV) ### Sharing with Dropbox If you want to use Dropbox then the best way is to install a sync client on your PC and set it up to automatically sync in the background. That way you will have the container on your PC and you can work on it locally. Note: The Home page will not work in the browser when you are on dropbox.org. --- name: WorkingRemote (Working V) ### Sharing with a server If you want to keep your intellectual property safe i.e. your files private, and use your own server, then you can use git to keep your files in sync. See the doc online for more information. --- name: ValueDomains ## Value Domains Value Domains are: * Areas where "value is being created or being supplied". * The names are similar to the department names used in organisations. * The names are abbreviated, i.e. Market is abbreviated to Mx. The structure in Boxxd is from the Workx Value Domain Model. In the _Works_ directory there are several value domain directories which can be used by the team to store their relevant documents. --- name: ValueDesc1 (Value Domains II) #### Value Domain descriptions __Part 1__ * [Ax - Asset](ecosystem/value-domains.html#Ax) (CM, Registration of numbers, API, Item Catalog, Patents) * [Bx - Build](ecosystem/value-domains.html#Bx) (Fabrication, Manufacturing) * [Cx - Customer](ecosystem/value-domains.html#Cx) (User Admin, 1st Level Support) * [Dx - Design](ecosystem/value-domains.html#Dx) (Content, Software Dev.) * [Ex - Enterprise](ecosystem/value-domains.html#Ex) (BizDev, Legal, Assist) * [Fx - Finance](ecosystem/value-domains.html#Fx) * [Gx - Grid](ecosystem/value-domains.html#Gx) (IT-Network, Service Points, Security, Facility Mgt. ), * [Hx - Human](ecosystem/value-domains.html#Hx) (Human Resource Management) * [Ix - Incentive](ecosystem/value-domains.html#Ix) (Incentive Systems) * [Jx - Joined Party](ecosystem/value-domains.html#Jx) (Suppliers, VIPs, Affiliates, Community, Partners), * [Kx - Knowledge](ecosystem/value-domains.html#Kx) (Business Intelligence, BPM, DataMgt), [More info about Value Domains here](ecosystem/value-domains.html) --- name: ValueDesc2 (Value Domains III) __Part 2__ * [Lx - Logistic](ecosystem/value-domains.html#Lx) (Sourcing), * [Mx - Market](ecosystem/value-domains.html#Mx) (Marketing, Sales, Advertising), * [Ox - Orchestration](ecosystem/value-domains.html#Ox) (Proj. Mgt, Automation, Long Term Planning) * [Px - Product](ecosystem/value-domains.html#Px) (PLM, Product Catalogs) * [Qx - Quality](ecosystem/value-domains.html#Qx) (Generic SLAs) * [Rx - Resource](ecosystem/value-domains.html#Rx) (Tech stuff needed for services) * [Sx - Service](ecosystem/value-domains.html#Sx) (Services to the end customer, partners) * [Tx - Teach](ecosystem/value-domains.html#Tx) (Training) * [Ux - User Experience](ecosystem/value-domains.html#Ux) (Of the product, services, frontends) * [Vx - Value](ecosystem/value-domains.html#Vx) (For the User, Enduser, Environment, Social) * [Wx - World](ecosystem/value-domains.html#Wx) (Top level, CEO) * [Xx - eXchange](ecosystem/value-domains.html#Xx) (For the exchange with others i.e. contracts) [More info about Value Domains here](ecosystem/value-domains.html) --- name: FAQ ## Questions and Answers Answers to [Frequently Asked Questions are here](faq.html) --- name: RootDir ## Container Structure ### _Root_ directory * _Home.html_ - The Home file where the outline about the product/service/venture is described via slideshows as well as having information about the container. * _Contents.md_ - an automatically generated list of contents, with a) sorted by directory and their contents, then b) a list of all files and the directory where to find it. * _Jotter.md_ - a file to quickly keep small notes for later use. --- name: HelpDir (Container Structure II) ### _.help_ directory This directory contains the manuals, cheatsheets, slideshows, on how to use the tools, about the containers structure, etc. [Jump to more info about Help](#HelpFunction) --- name: WiringDir (Container Structure III) ### _.wiring_ directory This directory contains files for the wiring of functions, such as * Scripts for slide shows, bots, * Css files * Fonts files * Meta information for automation The _.info_ directory contains meta information, i.e. information about the logical structure which can be used by automated scripts. Due to the use of the dot, it may not be visible on some user systems. --- name: ArchiveDir (Container Structure IV) ### _Archive_ Directory The _Archive_ directory contains previous releases of files or the whole _Works_ directory (if needed) ### _Items_ directory To keep the built parts such such as PDFs, exe files i.e. EndUser materials such as the book as pdf, marketing flyer as pdf, separate from the source and working file. ### _Works_ directory This directory contains the main working files organised as a _Value Domain_. Each [Value Domain](#ValueDomains) (i.e. process, department) has its own directory. --- name: TalkDir (Container Structure V) ### _Talk_ directory To help users have slideshows or media presentations ready to show to others, this directory can be used to store slideshows. Boxxd has a slideshow script built in, which can process markdown files, even for offline use. ### _Sources_ directory The designers, programmers, artists, etc., can use this directory as a working directory and keep their sources of programs, or contracts. Examples would be the draft of a book, scripts for a program, artwork for a flyer, a website. --- name: HomeFunction ## Functions ### Home page The Home page is the entrance point for users. Here you can link to slideshows and important documents, add status info, add tips and tricks on using the container. #### Extending To extend the contents of the Home page you will need to edit the _Home.html_ file. You can edit the file with a simple text editor and from around line 14, you can put in your stuff in Markdown format. Tip: If you have two displays you can have the browser open in one display and the text editor in another. After you have done your editing, just save it (normally with a ```
S```), go the browser and refresh it (normally with ```
R```) and you will see immediately your changes. --- name: TalkFunction (Functions II) ### Talk function The Talk function is a central place where presentations can be saved for the team, for management and others. It uses the [Slideshow](#SlideshowFunction) functionality. --- name: SlideshowFunction (Functions III) ### Slideshow The slideshow function allows people to run slideshows of their work. It is basically a two step process: * Drop a copy of the file into the _Talk/assets_ directory * Make a copy of an existing _Talk_ file, rename it, and edit the sourceUrl within it. It has a presentation modus - Just use the letter _C_ to clone the display, and _P_ to enter the mode. Have a go yourself - now - by typing _P_ and againg _P_ to get out of it! [More info about the slideshow here](plugins/slideshow-remark.html) --- name: IdeasFunction (Functions IV) ### Jotter The jotter is simply a text file in the main directory, called _Jotter-YourName.md_. Use it to make notes quickly without having to wade through the file directory. Tips: * Make it a habit to go through the file regularly to keep it small. * Write your initials with your note, so that others can see to who it belongs. --- name: HelpFunction (Functions V) ### Help The help system is to help people to find their way around the internal workings of the system. It is built on a collection of files in the _.help_ directory. It supports multi-languages, where the files are kept in their associated language directory such as DE, EN, ES. * Entrance - with an overview is via [_help.en.html_](../help.en.html) - The main document to enter the Help system * [More information about the help structure here](plugins/help-structure.html). --- name: HelpExtending (Functions VI) ### Extending Help If you want to add your own files you can put them there and just link to them. You will need to modify the following files if you want other people to find them: __In the Help files__ * _.help/help.en.html_ (An overview of help) * _.help/en/index.html_ (description of the files ) * _.help/en/help-guide.html_ (this help manual) __In the Home page__ * _Home.html_ --- name: FileNaming ## Under the bonnet ### File and directory naming The main directory structure is fixed. It has been designed to reduce clutter and at the same time allow non-technical people to read and understand it. Please feel free to use long names in file names so that they can be easily understood. --- name: FileExtensions (Under the bonnet II) ### File extensions A couple of the extensions which are used are: _.html_ is the file that will be shown in your browser. _.md_ is a text file using Markdown as markup (i.e. giving it structure) [More info about naming conventions here](myboxxd/naming-conventions.html) --- name: Tagging (Under the bonnet III) ### Identification tagging There are other tags such as: _.media.toml_ to document media information such as ownership _.tag_ to document a version number or a directory function. Note: A _bla-bla-bla.tag_ file might be empty, but it still being used as a visual marker. An example is the _.tag_ files in the _Works_ subdirectories. [More info about naming conventions here](myboxxd/naming-conventions.html) --- name: Headers (Under the bonnet IV) ### Headers and Meta info Files have headers containing information about the document such as title, subtitle, item number, authoring information, work still to do, etc. This information is to help: * Team members to see what is going on and to track changes * Automation scripts in extracting information and further processing More information [about file headers here](myboxxd/file-headers.html) and [about Meta information here](cheatsheets/meta-info.html). --- name: Automation (Under the bonnet V) ### Automation Doing tedious work is boring, is prone to errors, takes time, costs money. Boxxd is being developed to automate tedious work so that you and your team can concentrate on being _creative_. [More information about automation here](ecosystem/automation.html) --- class: inverse center middle ## For more info ...Just scream :-)