• This repository has been archived on 26/Oct/2021
  • Stars
    star
    559
  • Rank 77,640 (Top 2 %)
  • Language
    Rust
  • License
    Other
  • Created about 8 years ago
  • Updated almost 4 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

The open source design documentation tool for everybody

Heads up: reimagining artifact 3.0, check it out at artifact_py

Artifact: design documentation for everybody

Note: this project, and the python re-write, should now be considered abandoned. Please use it as you see fit.

artifact logo

Introducing Artifact

Artifact is the simple, linkable and trackable design documentation tool for everybody. It allows anyone to write and link their design documents both to each other and to source code, making it easy to know how complete their project is. Documents are revision controllable, can be edited in the browser and have a full suite of command line tools for searching, displaying, checking, exporting and formatting them.

b0rk scenes from writing design docs

Writing detailed design documents is one of the core pillars of quality software development. Design documents are how you capture the requirements (purpose) of your project and link them to your specifications (how you will build it). They let you get your ideas on paper before writing code, and help you have fewer painful refactors. They create a reference for developers and curious users of how and why your project was developed a certain way, and make it easier to refactor your project when that becomes necessary.

Even though design documents are critical to the quality of software, there are very few tools for writing them and integrating them into the larger context of a project. Artifact aims to fill the major gap in quality best practices by making writing good design documents useful to the average developer.

First of all, artifact makes it easy to write design documents in text files and link them by just specifying their partof attribute. This allows developers to put their design documents under revision control, review them using regular code review tools and use all the normal text processing tools (vim, grep, sed, etc) to view, edit and refactor them. Artifact also provides some command line tools of its own.

Secondly, design documents can be linked to source-code through a language agnostic syntax (#ART-name anywhere in the source code). Once linked, anyone reading the comment can easily look up the relevant design documents. In the same way, anyone looking at the Web UI can see exactly where a specification or test is implemented in code. Furthermore, if the name of a design doc changes, art check will tell you where your dangling references are. Never again will you have to be scared of refactoring your design documents because your references in code will be out of date.

Finally, artifact exports a beautiful rendered view of your design documents onto sites like github-sites (example) and you can edit in your browser using art serve. This completes the self documenting nature and allows anyone (even non-developers!) to view and edit the design documents of their project.

In this way, artifact aims to unify other quality best practices while also make writing design documents more fun and useful in your day to day development efforts.

Jump into artifact with the youtube commercial and the Tutorial.

Also, view artifact's own design docs.

Support The Project

You can support the project by staring it on github and 💚 sharing it with your friends, coworkers and social media. You can also leave direct feedback.

Build Status

Licensing

Goals

The intent of the artifact licensing is that:

  • The artifact application be open source for anyone to use for any purpose (dual licensed MIT + Apache).
  • Anything generated by artifact can be licensed any way the user wishes to, including the built static html pages.
  • Any documents, tutorials or specifications for artifact (except the code and logo) remain public domain and can be used for any purpose at all.

Specifics

All documentation and tutorials for the artifact application are released under the CC0 Creative Commons Public Domain License with the intent that you should feel free to copy, paste and modify any of the designs, guides examples or exported data for any purpose (including commercial) without the need of attribution. You can read more about CC0 here: https://creativecommons.org/publicdomain/

The CC0 license applies to:

  • All project docs
  • The Artifact Design Documents (also located in design/)
  • The Artifact Wiki
  • Any file or data created by any artifact command, including:
    • documents created by art init
    • compiled html/css/json files created by art export

The artifact logo (named Tula) is licensed under Creative Commons Attribution-ShareAlike (CC BY-SA) and can be used by the artifact project for any purpose without needing additional attribution. The artifact logo is located in ci/docs/logo and was originally created by packapotatoes.

Source Code License

The source code is Licensed under either of

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

More Repositories

1

strfmt

rust library for formatting dynamic strings
Rust
143
star
2

gpio

python gpio module for linux using the sysfs file access (/sys/class/gpio). Mimics similar Raspberry Pi IO libraries
Python
69
star
3

novault

ultra simple and secure vaultless password manager (beta)
Nix
56
star
4

path_abs

ergonomic paths and files in rust
Rust
49
star
5

defrag-rs

safe and efficient memory manager for microcontrollers
Rust
34
star
6

litevault

litevault provides an ultra lightweight command line password manager written in a single python file
Python
28
star
7

usertools

Arduino Library to offer debugging, errorhandling, simple threading and user interface, logging and many other tools
C++
26
star
8

stfu8

Sorta Text Format in UTF-8
Rust
25
star
9

stdcli

(pre-alpha) rust meta library for cli applications
Rust
18
star
10

termstyle

create and test the style and formatting of text in your terminal applications
Rust
18
star
11

yew_simple

Router for yew
Rust
13
star
12

Airbeam

C++
12
star
13

jrpc

ultra simple crate for types from the jsonrpc specification, for rust
Rust
10
star
14

dotfiles

vitiral's dotfiles
Shell
10
star
15

i2cdev

access to /dev/i2c* for linux devices
Python
8
star
16

taken

macros for taking ownership
Rust
7
star
17

tinymem

(ALPHA) tiny memory manager including ability to defragment memory pool. For use in uC and Linux
C
7
star
18

triforth

A typeforth implementation in tutorial-style assembly and forth (WIP)
Assembly
7
star
19

artifact_py

artifact re-imagined in python
Python
6
star
20

expect_macro

The expect! macro
Rust
5
star
21

diagnose

single tested python script for fast linux diagnostics
Python
5
star
22

notes

vitiral's notes
C
5
star
23

cloudtb

General "ToolBox" for programs developed by cloudformdesign.com
Python
4
star
24

zoa

serialized structured data and it's textual representation
Python
4
star
25

fiction-civboot

Civboot related fiction
3
star
26

wheat

wheat: a macro+const first low-level language
Rust
3
star
27

trfl

filesystem for fngi kernel
3
star
28

simple-quality

A short guide to quality best practices for developers
HTML
3
star
29

py3-smbus

python3 port of smbus
C
2
star
30

build_const

library for creating importable constants from build.rs or a script
Rust
2
star
31

bridge-rpc

bridged RPC protocol for microcontrollers
Rust
2
star
32

tmq

(pre-Alpha) Token Message Queue Library, written to be easily embedded
Python
2
star
33

nixos-configuration

My configurationf files for nixos
Nix
1
star
34

dungeon_game

A dungeon game for learning C++
C
1
star
35

typeforth.vim

vim syntax for typeforth
Vim Script
1
star
36

creative-commons-music

just some creative commons music I've found that I like for vidoes
1
star
37

DHT

DHT library that is compatible with Spark and non blocking (not interrupt driven)
C++
1
star
38

oserial

Object based serial port for python
Python
1
star
39

artifact-design

static web page for the design of artifact: the design doc tool made for developers
HTML
1
star
40

rag

rust documentation search engine [Alpha]
Rust
1
star
41

SearchTheSky

Search the Sky is a powerful a code re-factoring in a single tool for multiple programming languages.
Python
1
star
42

cfd_arduino_software

A mirror of my arduino install, with extra libraries added.
C
1
star
43

artifact-example

hello world example with rendered design docs
HTML
1
star
44

GaryDB

alpha single file NoSQLish database
Rust
1
star
45

ArduinoISP

Modifies the ArduinoISP library to allow talking through a serial port.
Arduino
1
star
46

spor_alloc

Small Allocator written in C for the spor/fngi kernel
C
1
star
47

wake

⏾🌊🛠 wake software's true potential
Python
1
star
48

adxl345-python3

fork of adxl345 library
Python
1
star
49

jsh

JSON-RPC standards for the shell
Python
1
star
50

pastebin

A place for me to paste stuff
1
star
51

HabitatMap

Arduino
1
star
52

pymakec

Create makefiles using python (2 or 3)
Python
1
star
53

replace.rs

cmdline utility to find and replace text using regular expression groups
Rust
1
star
54

vitiral.github.io

blog about life and computers
SCSS
1
star
55

fencsv

convert a chess fen string into human readable csv and back
Python
1
star
56

sparklibs

General libraries for the spark core
C++
1
star
57

raspi_i2c

very simple i2c module for the raspberry pi
Python
1
star
58

dataloss

short python script that can help detect data loss
Python
1
star
59

embedded_sensors

Based off of keiichishima RPiSensors. Designed for python3
Python
1
star
60

microtb

Shell
1
star
61

spidev

spidev for python3
C
1
star
62

El14_AudioServo

Audioservo from http://www.scary-terry.com/audioservo/audioservo.htm to demonstrate Beta of Eagle v7
1
star
63

jsoncmd

json rpc specification for the command line
1
star
64

anchor_txt

assign attributes to your markdown sections
Python
1
star
65

rust-embedded-design

design documents for the embedded rust ecosystem
1
star