0

I have an open-source project which requires me to create mathematical models to compute some things. I have to analyze some data to decide which model works well and determine the range of errors produced by the model.

I want to document this analysis, but I don't want to put it directly in the code because:

  1. It can be lengthy.
  2. It does not fit into any class or method.
  3. Because of 2., it would be hard to find it later.
  4. There are tables and even images. Also proper typesetting is going to be helpful.

I am looking for the most appropriate format for the design documentation. I've thought of a few options:

  1. docx: Requires proprietary software to edit it.
  2. html: Need to know html syntax to edit the document.

Are there any better formats for writing design documents ?

Christophe
  • 74,672
  • 10
  • 115
  • 187
jetstream96
  • 19
  • 2
  • I think this question should not be closed as out of scope: the question is a about the choice of a file format to share design documentation in a project. It doesn't ask for tools nor for resources. I think it could fall in the [category](https://programmers.stackexchange.com/help/on-topic) "development processes" (management of documentation) – Christophe Aug 21 '16 at 21:46

5 Answers5

1

I neither like docx (for it's a proprietary format) nor html (because it normally ends up having quite a lot of files with the reader not knowing where to start.

pdf is a good format to distribute documentation (Maybe created using LaTex), pure text files work well as well. Mathematical software might, however, imply formulas and images that don't work very well in text files.

If you want to go for an editable document format that supports formulas and embedded graphics, I'd go with the .odt text format that is understood by most modern word processing software, including MS Office and Open/Libre Office.

tofro
  • 891
  • 6
  • 10
  • 1
    Office OpenXML is also an ISO standard, just like OpenDocument. Calling one an open standard and the other a closed proprietary format is a bit strange, for two standards published by the exact same standards organization. – Jörg W Mittag Aug 21 '16 at 18:01
1

You could also use a wiki, or sphinx to document your designs. Personally I use sphinx, I can get code syntax highlighting, mathjax, tables, figures, hyperlinking and much more. It also has the added benefit of being able to automatically put that into html, pdf, epub and many other formats.

Also depending on the programming language you are using you could use a jupyter notebook which allows for text and code to make a powerful document.

Greensheep
  • 19
  • 3
  • Thank you. Both sphinx and jupyter looks pretty powerful. However, it might be a little inconvenient for others to view or edit since my project is in C#. – jetstream96 Aug 22 '16 at 04:41
1

For an open source project, I would advise not to rely on close proprietary format (i.e. no docx).

In the life of the project, the document will certainly evolve (imagine release 3.0 ! ). So I'd suggest not to use formats that make it difficult to maintain (i.e. not PDF, as it is more for distributing/archiving than editing).

If you'd like a larger part of the community to read the file easily and to contribute, I'd also avoid exotic formats that require to find rare third party tools (i.e. not Latex, unless you target primarily a population of scientific researchers)

My suggestions in order of preference:

  • raw text à la readme.txt - unicode provides lots of symbols now and formulas could be expressed in a functional way. Unfortunately you'll have to avoid this option because there's no way to insert diagrams/pictures.
  • markdown - easier than HTML - possible to insert schemas - cleaner presentation than with raw text. In addition, services like github display natively this format, which makes it a good choice for open source. It doesn't let you choose typesetting. Unfortunately doesn't support MathML yet, so you'd have to express formulas the functional way.
  • OpenDocument (aka .odt) - powerful, standardized (ISO), includes support for math formulas, widely supported and used - definitively a good choice.

HTML could be an option as well, with MathML for the formulas. However, I think that for an author it's less convenient to use, so that the balance would be in favor of one of the above ones.

Christophe
  • 74,672
  • 10
  • 115
  • 187
  • Office OpenXML is also an ISO standard, just like OpenDocument. Calling one an open standard and the other a closed proprietary format is a bit strange, for two standards published by the exact same standards organization. – Jörg W Mittag Aug 21 '16 at 18:00
  • @JörgWMittag I think there is a difference in terms of licensing related to required patents between [Microsoft's standard](https://en.wikipedia.org/wiki/Office_Open_XML#Licensing) and [OpenDocument ](https://en.wikipedia.org/wiki/OpenDocument#Additional_royalty-free_licensing). The licensing terms of the first would be more restrictive [according to this analysis](http://www.groklaw.net/articlebasic.php?story=20051202135844482) than the second, but I'm not a legal expert. – Christophe Aug 21 '16 at 18:28
  • @JörgWMittag In addition, it appears also that several european governments have adopted ODF and rejected OOXML as interoperatbility standard for documents (e.g. [UK](http://www.computerweekly.com/news/2240225262/Microsoft-attacks-UK-government-decision-to-adopt-ODF-for-document-formats), [France](https://www.april.org/en/french-government-it-directorate-stands-its-ground-odf-supported-ooxml-rejected) ). Among the griefs agains OOXML is that apparently not all the .docx would be compliant with the OOXML standard. – Christophe Aug 21 '16 at 20:56
  • Thank you for your input. MathML is pretty cool. For now OpenDocument seems to be the choice. – jetstream96 Aug 22 '16 at 04:28
0

I often use OneNote, the basic version is free. It is like Word, but you can embed files. You don't have to save every piece of documentation as a single file and sort them into folders, you can sort them in registers and pages. That way you only have one file. It also has some features from HTML, you can link every page in the OneNote to another. Formulars and images also work well.

The problem is that you need OS X or Windows because there is no other viewer for other operating systems.

The format is proprietary what makes it even worse.

But the best format is more of a personal opinion and if you or your potential viewers of the document don't own OneNote, then this is the worst format.

KeksArmee
  • 135
  • 6
0

Consider using latex. There are open source application for OS X, Windows and linux.

Robert Baron
  • 1,132
  • 7
  • 10
  • Unfortunately letex is not user-friendly. – jetstream96 Aug 22 '16 at 04:51
  • To each their own. Although I do agree with you that latex is not the easiest program to use, it does provide for more better placement of images and graphs than ms word. When I tried wirtting a document with captions I found that latex was easir to get all of the formatting correct. Plus it didn't anything unexpected. – Robert Baron Aug 22 '16 at 18:55
  • Sure, it looks like latex manages the formatting itself quite well. I heard that it's very popular in the scientific community but the people who view my document may have never used latex before. – jetstream96 Aug 23 '16 at 02:21
  • You can provide the latex document and a pdf that is generated from the latex document. – Robert Baron Aug 23 '16 at 18:41
  • That can be a solution. I may as well give it a try when I have the time. Thanks for the suggestions. – jetstream96 Aug 23 '16 at 18:59