Documentation Standards

From Open Source Ecology
Jump to: navigation, search

Introduction

Post Oct 2018 Intro

These documentation standards are so detailed and comprehensive that they become difficult to digest for the documenters who do the work. Here is an intermediary documentation process for how to prioritize different parts of these documentation standards so that contributors actually document things with the energy they have.

Please see P:Documentation Standards::Iterative Documentation Flow.

Pre Oct 2018 Intro

In Dan Benamy's opinion, this page is confusing and needs some cleanup, focusing, clarifying, and/or splitting up. Normally he do that work but it looks like Marcin set up this page and he doesn't want to get in Marcin's way. Dan will just add a link here to How to Structure the Wiki for GVCS Machines which he'd normally integrate into the page if he understood it :-)

As OSE moves towards viral replicability, it is important to create effective documentation standards. This applies to the work of OSE and also towards creating a broader platform for open source product development. To this end, we are studying existing open source industry standards - to pick out existing best practice and to integrate these into a larger platform. The strategy is to remix as many existing tools as possible - while inspiring the related players to contribute to a greater platform.

The scope of Open Source Ecology involves machine and organization level items leading to the Open Source Economy. In Phase I (January, 2013), we are defining the standards for the 50 GVCS machines, which is intended to be a beta test for a larger platform that scales to any number of items - encyclopedic scope. Organizational aspects for creating the open source economy will be developed in Phase II (February, 2013).

The current priority is to standardize a format for documentation on the OSE Wiki.

Strategy

  • Define problem statements and solutions - [1]
  • Seed the process, find Product Owners
  • Invite Key Players for review to generate buy-in
  • Host a Hackathon to deploy a minimum viable product based on community buy-in
  • Keep developing platform
  • Monetize platform for self-sustainability of effort

General Approach

We would like to develop a platform for uniform acccess to all open hardware, by virtue of defining a content taxonomy. This includes tagging to make Open Source Hardware (OSH) universally findable - so that it can be searched and results displayed. This includes defining uniform content taxonomy and standards (such as CAD, BOM, fabrication drawings, etc.). Define genearally-accepted best practice taxonomy for delivery of content and standards (such as Sketchup model, YouTube video, LibreCAD dxf file, etc). Open Source Warehouse would be a platform where content would be submitted and viewed via an easy-to-use platform.

User Stories

We will deploy a community version of the Documentation Platform in April. In February, we will deploy an OSE internal version which can be upgraded by others, with basic functionality that allows us to organize content from the entire wiki. The goal is to index and link to a large quantity of modular content. This modular content can subsequently be displayed in any viewing/structuring platform.

Replicator

  • As a builder, I want to access the build instructions, videos, and BOMs for a successful build.
  • As a replicator, I want to assess the state of completion of the product. I also want to disambiguate between product that does not exist vs. documentation that does not exist. Ie, some Product might be built, but documentation may not exist - so absence of documentation does not necessarily mean absence of product.
  • As an open source economist, I need to see the economic analysis to see scaling potential of a manufacturing enterprise for a machine.

Developer

  • As a developer, I need a place to upload content, and I need a clear structure so that I know where to upload it.
  • As a developer working on a further iteration, I need a place to update the documentation without messing up the structure and integrity of prior documenation, because some changes of content also affects other parts of the documentation.
  • As a minor developer who made only a small improvement, I need to make sure that my work is documented.
  • As a reviewer, I want to see a history of how the machine versions have evolved over time, and I want to see performance calculations to verify them.
  • As an information architect, I need to know how the documentation modules fit together.
  • As a database designer, I need access to a taxonomy of all the content, and I need a sample of all the modules to test my display methods.

Publisher

  • As a publisher, I want to publish a machine manual readily.

Video Editor

  • As a video editor making instructionals, I need access to videos of various builds the results, and issues encountered during builds.
  • As an eye-candy video editor, I need footage of sparks flying during production, as well as other flashy footage.
  • As an animator, I need to understand the operating principles so I can make an explanatory rendering. I also need access to the 3D objects so I can use them in my animations.

Basic Wiki Version

Non-Structured OSHW Documentation:

edit

Sample Implementation

Available Documentation Tools

Working Document

edit

Open Hardware Documentation Outline

edit

Documentation Taxonomy

edit

Samples

Information Architecture

[https://docs.google.com/drawings/d/1MUl31a7eFGNMFVP90Gq_mXiJ4d0U3Jgdw776z5qG1kE/edit edit

Documentation Platform - Entity Relationship Diagram

Architecture for programming the user platform:

edit

Documentation Workshop Organization

OSHW Documentation Handbook

edit

Documentation Platform Principles or Specification

  • Language agnostic platform
  • Readily publishable in part or in full in hard copy or digital copy
  • Promotes the open source economy and distributive enterprise
  • Clear contributor agreements and user license
  • Work Product is a Protocol, not Platform. Distinction is Protocol can be implemented on any platform.
  • Platform, hardware, and software agnostic. Uses open software formats; accepts proprietary formats so they can be translated.
  • Contains a commit and quality assurance mechanism
  • Upvotability and quality upgrade mechanism, versioning
  • Modular design of documentation, clear modularity standards for how documentation components fit together, and easy interfaceability between modules
  • Resource Description Format markup for semantic web compatibility. Tagging and markup for mashup and remix purposes. API for interoperability with other platforms.
  • Breadcrumbs - location guide or secondary navigation scheme
  • Well-defined tagging standards.
  • Entry-level access for contributors (not a geek protocol)
  • Entry-level access for developers
  • Incentivizes participation with other open source and closed source platforms.
  • Glossary is incuded, platform is self-explanatory.
  • Meritocratic governance
  • Provides an assessment mechanism for 'state of open-sourceness' of projects
  • Facilitates quantitative assessment or statistics about open hardware projects in general
  • Encourages DIY projects to join open source economic framework, and invites uninitiated DIY projects to add value to their work and to the world by making their work more visible
  • Fosters Technical Literacy
  • Ready verifiability of results
  • Backup strategy well-defined
  • Contributor rights clearly defined and designed as a Badge or Distinction. Crowd sourced contributions from users and developers; careful log of contributors

Work Product

edit

Value Proposition

The value that we propose to add to defining documentation standards is:

  • Basing platform on existing tools - building on open source industry standards and using non-open source tools only if necessary until they can be substituted.
  • Developing interfaces between existing tools, not developing new tools (remixing and mashup)
  • Documenting that interface with Brick Press as our test case
  • Defining a protocol for documentation based on existing tools
  • Getting feedback from the greater community, and defining a role for a Documentation Director for Scalable Open Source Product Distributive Enterprise Development Projects.

Documentation Design Rationale

The scope of effective documentation standards for OSE includes Machine, Organizational, and Wiki level areas of documentation.

Organizatinal Level

  • The organizational level involves documentation related to running a GVCS-based development, production, or other applied project.
  • Enterprise development documentation.

Machine Level

  • Understanding the standards makes it possible to navigate both graphically and via the address bar on the OSE wiki - to access any piece of documentation for any machine.
  • Machine naming is standard. Currently, the names used on the main site at opensourceecology.org are used.
  • Each machine has a Core and Supporting documentation set. The Core set includes those pieces of documentation that are indispensible for the safe and effective building and usage of GVCS tools by inexperienced builders/users. Supporting documentation is that which allows for the modification, remixing of modules, and other hacks on the machines. It also includes that information which makes replication easier, but which is not critical to such replication - by a novice builder.
  • Each Machine has a finite, well-defined set of Core Documentation and Supporting Documentation.
  • Supporting Documentation consists of Wiki-level (such as Links section or Index) and Machine-level items (such as CAE analysis - noncritical but desirable for replication)
  • Standards are consistent with Open Source Hardware Association Open Source Hardware Definition.

Wiki Level

  • Each machine has a particular set of wiki-level Supporting Documenation items - such as Links (example below). Standards are defined for each of these Supporting Documentation item

Specific Wiki Page Structure

Current work on Frame_DXF_Files indicates that a rigorous structure of documentation needs to occur for completeness. This structure should be represented as an infographic with design rationale (for documentation steps) captured.

Links

Past Work of OSE

Related Work

Meta

  • Resource Description Framework (RDF) - [7]. From Wikipedia article - Creative Commons - Uses RDF to embed license information in web pages and mp3 files.
  • Semantic Media Wiki extension - SMW adds semantic annotations that allow a wiki to function as a collaborative database - [8]
  • Semantic Web Challenge
  • Project Halo - The appendix to Paul Allen's new book, Idea Man, describes several challenges in artificial intelligence for which Project Halo is actively seeking solutions. We are actively seeking people and organizations with serious and well-grounded technical ideas that can result in significant progress against these challenges. Please use the Idea Submission Form to contact us with a sketch of your idea, along with any supporting evidence that it will be successful. Please do not send confidential or proprietary information to Project Halo using this site or through any other means. - see http://www.projecthalo.com/

Literature

Open Source Hardware Project Listings

Links

Retrieved from "https://wiki.opensourceecology.org/index.php?title=Documentation_Standards&oldid=289083"