 |
 |
> On Sep 10, 2020, at 6:39 AM, Polutta, Melanie <[log in to unmask]> wrote: > > All, > > I am interested in hearing about markup formats, software, and processes to managing and publishing cataloging documentation for use by many communities. We need a way to encode the documentation so that it can easily be updated, versioned, and outputted as a searchable website and PDF for downloads. When you say ‘many communities’ do you mean many different groups producing software, or many different types of people producing documentation? And is this new (electronic) documentation that can easily be parsed, or maybe even have standards pushed on the people writing it if it’s for internal stuff, or are you also going to be cataloging older documentation? If you’re just dealing with current software, then Write the Docs is probably a good point to dig If you’re dealing with other types of documentation, you might want to try reaching out to groups like iFixit (writing instructions on how to repair things) or even wikihow (because they might have ideas of where else to look, not because I’d advocate for something as unstructured as a wiki for this) For physical documents that need to be scanned and such, you might want to contact Jason Scott (textfiles.com). He set up a website archivecorps.org after he rescued a bunch of tech manuals in western Maryland. I know back when I worked at Goddard, I had talked to someone about how they were having trouble capturing documentation for satellite and spacecraft. I *think* it was Gail Hodge, back when IIa still had the contract to manage the library And they probably had different concerns, unless you also need to host ‘administratively controlled information’ that’s covered by arms proliferation laws. (Mission launch information counts as ‘dual use’) > Currently we are looking at various flavors of XML markup, and the software needed to output that, but we didn't want to limit our view. Do any of you all have suggestions? And more importantly, the reasons for your suggestions? I think it probably depends on what sort of documentation you’re dealing with (do you need table support and the like), but for simplistic stuff, I’d probably lean more towards MarkDown or one of its forks if you consider it documented well enough for your archival needs. For metadata, I’m leaning more towards YAML these days over XML, unless you expect that you’ll need the extensibility that you can get by specifically qualifying each element, and the ability to assign both values and attributes to individual elements (Although I admit that trying to go back and add that functionality is near impossible — I’m currently trying to figure out how to document FITS files (The scientific image format) so people know when metadata fields are following published standards or are ad-hoc and use names that collide with the standards) -Joe Sent from a mobile device with a crappy on screen keyboard and obnoxious "autocorrect"