Follow

publishing design documents? 

What's a good archival method for publishing design documentation to produce a piece of scientific equipment used in a published paper? I developed something fairly complicated and would love to document it so that others can actually replicate what the people using my tool did.

Github and gitlab don't feel safe, neither does google docs, can I upload things like STP files as attachments with arxiv documents?

publishing design documents? 

Pre-emptively, the paper was published before I knew they were writing it and does not contain this information that I think is useful to others and would look good on my CV to have there. I am pretty sure the canonically correct answer is "as supplementary material" so I guess what is a second-best option after that.

publishing design documents? 

@bipolaron
I made this :) you can use it or I can make a page documenting how to make your own! (it's mediawiki and semantic wiki with a few extensions)
wiki.auto-pi-lot.com/index.php
and example
wiki.auto-pi-lot.com/index.php

publishing design documents? 

@jonny I like the concept, but I'm worried about archival aspects. I know I don't have the competence to keep a functional repository going, I don't trust github, gitlab, etc... how do you make it so that this stuff doesn't entropy away?

publishing design documents? 

@bipolaron
there's sort of a point where this becomes a social/philosophical question rather than a technical one to me, and there are many senses of archivalism. nothing lasts forever, the thing that preserves information is social organization - archive.org is much more a collection of people than a set of hard drives or a tech stack.

different archival modes have different implications for social organization. /1

publishing design documents? 

@bipolaron
in the absence of strong social organization, the thing I believe preserves longevity is interoperability and its relatives. This has technical reflections like the medium, and conceptual reflections like the notion of transclusion in wiki culture.

this wiki is an experiment in several of these senses of archivalism. it is built on a thoroughly institutionally supported medium (mediawiki, core tech of wikimedia aka Wikipedia) /2

publishing design documents? 

@bipolaron
the semantic component is exportable to RDF, another format that is (controversially) well supported. the entire site can be exported to XML by anyone.

the goal is to make a collection of interoperable and transclusive wikis like this, so this wiki is less important than building the culture around it.

practically, archival is trivial - archive.org does the trick. discoverability is harder, but exports can be made for eg. figshare and etc. /3

publishing design documents? 

@bipolaron
the wiki is built to make reference to other representations: use the [[Has DOI::]] semantic tag to refer to a doi-indexed version. we can experiment with automatic export and updating too.

point being I also see the lack of options in this space, am attempting to draft something for it, and the only way that works is if it becomes "real" for other people too. /4

publishing design documents? 

@bipolaron
but I'm not asking you to trust me, random person on the internet - hence the design around interoperability and export. you don't need to trust me if the idea works, because you can always take and keep what you contribute.

it's an experiment, and we'd love to host your designs as well as do whatever we can to inspire the next iteration, whether it's yours or otherwise ❤️

publishing design documents? 

@jonny oh, I may have misunderstood what it was in looking too quickly, it looked to me like a self-hosted wiki I'd need to maintain on my own server based on the custom domain name.

is it intended to be a generic repository for technical documentation? I assume my use case is a little unusual in that I basically want to make it discoverable that it is linked with the research paper's methods. Given the medium, something hosted on arxiv or the like seems reasonable.

publishing design documents? 

@bipolaron
it is something that I host, but can be rehosted easily :) it is indeed intended as a generic repository, or more specifically a seed of a family of generic repositories. it is designed to link to papers (and to link from paper to repo would just be a hyperlink), but the pages can also be exported to upload to something like zenodo.

publishing design documents? 

@bipolaron
arxiv would also work, but the problem is that it only hosts PDFs, which are a bad fit for technical documentation like this - relatively static, not capable of supporting variants or public contribution, discussion, troubleshooting notes that come up in secondary builds, everything in one document instead of split out to component parts that can be reused, etc.

publishing design documents? 

@bipolaron
so up to you if it seems like a good fit! like I said, something I made in the absence of a good way to do what you're trying to do, so I don't have the kind of institutional longevity of other archives, but trying to make something that works!

re: publishing design documents? 

@bipolaron Sounds like ancillary files to me.

stp being 3d files and not a binary, I assume

arxiv.org/help/ancillary_files

re: publishing design documents? 

@bipolaron
maybe the Open Science Framework is an option for you: osf.io/.
The system is very flexible and I feel more trustworthy than GitHub, etc -- from their FAQ: "OSF is maintained and developed by the Center for Open Science (COS), a 501(c)3 non-profit organization. "

re: publishing design documents? 

@miguelarbesu This looks perfect, thanks!

re: publishing design documents? 

@bipolaron glad to help 🙂

Sign in to participate in the conversation
Scholar Social

Scholar Social is a microblogging platform for researchers, grad students, librarians, archivists, undergrads, academically inclined high schoolers, educators of all levels, journal editors, research assistants, professors, administrators—anyone involved in academia who is willing to engage with others respectfully.