Artifact: design documentation for everybody

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.

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.

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

Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

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.

l-x-u / artifact