6

I work for a software company and am thinking about publishing our training manuals as open (creative commons) licensed documents, so that others can use them, edit them, and derive new products/training from them.

The thing is, I'm not really sure what format would be best to publish them in. Word (though common) doesn't seem very open and PDF (though open) doesn't seem best for allowing others to make changes or edits.

Open Document Format (ODF) seems a possibility - I'm just not sure if it's got enough of a user base that it is practical. For example, I don't think you could open ODF in Google Docs.

Does anyone have any suggestions?

Improve this question
4
  • Google Docs help says this about supported formats: These are the file types that can be converted to a Google document, spreadsheet, or presentation: For documents: .doc, .docx, .dot, .html, plain text (.txt), .rtf
    – Mark Ireland
    Sep 11, 2014 at 18:22
  • 2
    Perhaps provide them in multiple formats to suit the varying needs. I would start with MS-Word and export to other formats.
    – Andrew - OpenGeoCode
    Sep 11, 2014 at 19:32
  • Thanks for all your suggestions folks. I really hadn't thought about Github (which is so obvious once you say it) and markdown sounds a good idea too. I think the key hurdles are going to be technological (whether we can export the materials in the format we want from the tool we use). It's going to be interesting and - I hope - fun!
    – Mark Ireland
    Sep 12, 2014 at 20:04
  • google docs has problems with odf, which is why the uk gov is not utilizing google docs, as odf is their national format....don't let non-use dissuade you! encourage/enlighten/teach your users about odf.......by providing it!
    – albert
    Sep 23, 2014 at 2:23

6 Answers 6

Reset to default
10

Ideally, like @Andrew - OpenGeoCode mentions, you would release it in multiple formats.

I would really suggest you look into organizing it into a e-book written in Markdown and hosted on Github. There are several advantages to this such as a built-in change log, being able to let people to (publicly) fork your document(s) and share their changes with the public, give you a workflow to bring in suggested changes (pull requests), and much more.

An example of this can be seen at https://github.com/truevault/hipaa-compliance-developers-guide.

There are a number of ways to convert your Markdown to PDF, HTML, etc. (1, 2). You can also google for tools to convert your existing ODF/Word/etc documents to Markdown.

Improve this answer
0
6

The other suggestions on here are great, and I would echo the recommendation to consider Github if you want people to be able to easily edit your product for creating their own versions. This will also help you track the edits that have been made so you can learn more about what people do with your manuals.

If you want to learn more about the definitions of open formats and open standards, there are some links rounded up here that might be of interest: http://sunlightfoundation.com/opendataguidelines/#open-formats

(Disclosure: I work for Sunlight Foundation, which curated those links.)

Looking forward to hearing what you choose to do!

Improve this answer
3

Do you know specifically who will be editing your manual or you plan to open them and see what happen?

If you already have contact with potential editor and contributor, just ask them what makes sense to them.

Markdown and Github is a great option if you community knows how to use them.

Improve this answer
1
  • your mention of publisher got me thinking -- I remember seeing something a while back where someone who was writing a book (I think it was for O'Reilly) discussed the process and the formats they used (which could then be converted into PDF and other formats). A little more digging and I found that they're one of the original collaborators of the DocBook standard.
    – Joe
    Sep 12, 2014 at 17:39
2

MediaWiki is a good alternative in getting your documentation out to the public without requiring knowledge of GitHub.

There are some Extensions to link to GitHub, noteably

The GitHub Extension allows to embed files from GitHub.

This GitHub Template provides a convenient way of linking to mediawiki source files hosted in the github mirror

Improve this answer
1
  • nice! i'm aware of mediawiki's existence, but barely anything above that....checking it out now
    – albert
    May 23, 2015 at 0:41
1

I think the answers here are pretty comprehensive, but I am not sure how complex the documents that are being produced. Sometimes, Markdown isn't robust enough to support advanced documents (e.g., footnotes, bibliographies, etc.)

I would also recommend looking at Pandoc or Multimarkdown. It won't necessarily render in GitHub, but is a good way to keep a "simple" format that can be edited by others.

Improve this answer
1

if you set your baseline as JSON, conversion to all of the formats listed is trivial, and can be easily automated.
not listed, and perhaps relevant here is JSON-LD, although i'm not very familiar with it, so that could be wrong: definitely worth a look into....
emphasis:
publish html so that its indexed and searchable on the web; moreover, if you use web standards and adaptive development techniques, you are already covering the vast majority of user agents likely to be utilized to read your docs.

publish spreadsheet format(s) which provide easy access to the data, allowing users to manipulate it as they see fit, offering the greatest possible ratio of the data being utilized, and utilized well.
lack of .ods use, and overall knowledge of the format (at least in america) is dissuading, but don't let it be a deal breaker! use it as an opportunity to educate the public, while supporting openness. you can always provide other format(s) as well, but i highly encourage you to ensure you are publishing .ods first and foremost for spreadsheets.
in this case github sounds ideal for hosting, but the best solution is ckan, wherein you are taking the extra steps to own your data, which is a key principle of openness. github is the bomb dot com, but at the end of the day, its still third party and you are at its mercy.

if you use google docs, they already provide multiple formats for download, so all you have to do is upload one type;
gdocs also lessons barriers to access like github with its broad user base, as well as permitting sharing and publishing, HOWEVER YOU HAVE TO SET THESE OPTIONS. google doesn't do them by default.

office365 actually provides better cross-browser capabilities than google drive, although if i remember correctly its formats are limited....gdrive actually has more functionality in firefox than chrome on win....go figure

pdfs serve a purpose....although i'm still in denial about it...one case in particular is for drawings/designs, usually too intricate for html/css....but thats an oxymoron because there is nothing you cannot do with javascript (also svg ftw!)

i do not see a purpose in ms word, .doc, or .docx at all. i'm sure there is one use case to destroy my view, but i'm not aware. anything you can do in word, you can and should be doing in html at the very least...if you feel like you have to use word, use .pdf!

Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.