las16-506: the future of 96boards documentation

The Future of 96Boards DocumentationRobert Wolff

ENGINEERS AND DEVICES

WORKING TOGETHER

Who am I?

● Robert Wolff

● Engineer - Technical Writer

● Team: 96Boards at Linaro

Twitter: @sdrobertw and @96Boards

IRC: sdrobertw

Email: [email protected]

Coursera - IoT Specialization for DragonBoard 410c

Github - 96Boards and Linaro documentation repositories

OpenHours - www.96Boards.org/OpenHours

Author: Robert Wolff - [email protected] (09/30/16)

http://www.96boards.org/OpenHours

mailto:[email protected]

ENGINEERS AND DEVICESWORKING TOGETHER

Outline - The Future of 96Boards Docs

● Current Documentation

● The Old Ways

● New Approach

● Document “Contribution Cycle”

● Rethinking the Cycle

● The Process




Current DocumentationWhat’s so special about any of it?




WORKING TOGETHER

Current Documentation - Types

● PDF○ User Guides

○ Hardware Manuals

○ “How to” Guides

○ More...

● Wiki○ 96Boards

○ Linaro

○ Board specific

● Github Documentation Repositories○ 96Boards

○ Linaro

○ Other...




Current Documentation - Initial thoughts?

● Scattered

● Repeated

● Out dated

● Inconsistent

● Lack of ownership

● Consolidate

● Remove (if possible)

● Maintain

● Build out / template

● Assign ownership




Current Documentation - Initial thoughts?

Organize

Structure

Set/Use Conventions




The Old WaysA current approach




The Old Ways - A good start...

● SoC programmer’s Technical Reference Manual - PDF

● Hardware User Manual - PDF

● Schematics - PDF

● Getting Started Guide - PDF

➢ What happens when users want more?

➢ What happens when something needs to be changed?




The Old Ways - New doc?

Create a document

Throw it anywhere on the Internet

Don’t tell anyone

Never updateAuthor: Robert Wolff - [email protected] (09/30/16)



The Old Ways - Change doc?

Make a new doc,

put it anywhere,

without telling anyone...




New ApproachHow much better can it be?




New Approach - Goals

● Reduce static documentation

● Increase dynamic documentation

● Allow Vendor contribution and ownership

● Encourage community contribution and ownership

● Reduce points of contact

➢ What happens when users want more?

➢ What happens when something needs to be changed?




Document “Contribution Cycle”The hours add up and cost everyone $$$




Document “Contribution Cycle”

Community

Static Document

Document Owner

Use

Report

Report Raw Document

Fix

New Version

Error

Upload

96Boards

Inform

Fix




Rethinking the CycleResource allocation with minimal points of contact




Rethinking the Cycle

Community

Dynamic Document

New Document

Use

Report

Fix

Error UploadFix New

Document96Boards





● Quick and easy document modifications

● Straightforward document creation

● Community driven

● 96Boards maintained

● Website rendered




WORKING TOGETHER


96Boards will:

● Buffer

● Share

● Contribute

● Expand

● Maintain

With help from:

● Linaro

● Vendors

● Manufacturers

● Community

● Anyone...




The ProcessWorkflow, tools, methods, execution




Consistency




WORKING TOGETHER

The Process - Tools

Welcome to 96Boards:

● Landing page with core material

● Core Material and Setup

● Templates and instructions

● Support and Community




WORKING TOGETHER

The Process - Tools

Github:

● Git for command line

● Using Markdown and reStructured

● Downloadable PDFs are welcome

● Hosting images

● Share all 96Boards generic docs




WORKING TOGETHER

In Conclusion

We aim to provide:

● Dynamic

● Streamlined

● Consistent

● Well Maintained

● Robust

Documents

Created and supported by:

● 96Boards

● Linaro

● Vendors

● Manufacturers

● Community




WORKING TOGETHER

Links

➢ www.96boards.org

➢ www.96boards.org/openhours

➢ www.github.com/96boards/documentation

➢ www.github.com/Linaro/documentation

➢ www.coursera.org

➢ www.Linaro.org


http://www.96boards.org

http://www.96boards.org

http://www.96boards.org/openhours

http://www.96boards.org/openhours

http://www.github.com/96boards/documentation

http://www.github.com/96boards/documentation

http://www.github.com/Linaro/documentation

http://www.github.com/Linaro/documentation

http://www.coursera.org

http://www.coursera.org

http://www.linaro.org



Thank You

#LAS16For further information: www.linaro.org

LAS16 keynotes and videos on: connect.linaro.org



Extra Slides


Useful Logos

Download Hi Res logos from here* to use on your slides

*http://link.linaro.org/logos

http://link.linaro.org/logos

http://link.linaro.org/logos


This Slide is for when Two Columns are Needed● You can use this for two columns of

bullets

● Or you can replace one column

with an image or diagram

● This could be a second column of

bullets

● Or it could be a table, image or

graphic


WORKING TOGETHER

Alternative Content Slide● If you have a more succinct message, use this slide

las16-506: the future of 96boards documentation

Technology