search

ydluo / qdyn

A Quasi-DYNamic earthquake simulator
59 stars 28 forks source link

Suggestion for documentation: Github Pages #14

Closed martijnende closed 5 years ago

martijnende commented 6 years ago

At the moment we contribute to the documentation via a Google Doc, which is not an ideal solution in my opinion. We could switch to using Github Pages as a way of documenting our code, in which the documentation is generated from one or more Markdown files contained in the /docs directory (in the same way as our Readme works). I have copied a piece of the current documentation from the PDF to my fork, see this page for the result. It will be a bit of work to fully copy the entire documentation into a Markdown file (my guess: 2-3 hours), but I see the following (long-term) advantages:

  1. Documentation is kept alongside the code within the repository, rather than on a Google Drive
  2. Individual features/scripts/examples/tests could be documented individually, and linked to the main documentation page. In this way not everything has to go on one single page/document, which allows for a more clearly structured documentation
  3. Changes in the documentation are kept as commits, so version history is maintained
  4. Related: updates to the documentation (or lack thereof) can be tied to individual pull requests
  5. Anyone with a Github account (not just QDYN core developers) can contribute to the documentation and make suggestions via pull requests
  6. Markdown (HTML) is a bit more flexible in terms of formatting, I feel

Any thoughts or feelings?

jpampuero commented 6 years ago

I agree using Google Docs for the manual is not a great solution, and I like the advantages of what you proposed. A couple of questions to make sure it's a developer-friendly solution: Is there a Markdown WYSIWYG editor or is it only edited via a text file (like editing LaTeX files the old school way)? Is it easy to include figures, equations and references to sections, figures, equations (by labels, as in LaTeX)?

martijnende commented 6 years ago

I'm not a Markdown expert, but I have seen some methods of linking to headers (like this one referring to the header below). [EDIT: this used to work, but appears to be broken now. Looking for a fix...]

Equations in Markdown

Equations can be inserted by rendering an equation in CodeCogs and embedding it as an SVG image, like this:

This method also supports inline equations, so that symbols like can be shown within the text. It may get a little cumbersome if you have lots and lots of symbols/equations to show.

My impression is that Github Pages is a bit more flexible than the regular Github-style Markdown (as used in this post), since people build entire websites out of it (example). It helps if you're familiar with HTML/CSS, but it should be no more difficult to maintain/contribute to the documentation than it is to maintain the Readme file of this repository.

WYSIWYG?

You can pick your favourite editor from a long list (e.g. here), or just edit things on Github and check the Preview tab once in a while.

jpampuero commented 5 years ago

Would there be a way to export the user manual as a well-formatted pdf booklet?

martijnende commented 5 years ago

Yes, markdown can be rendered into a PDF (similar to LaTeX)

jpampuero commented 5 years ago

If the resulting pdf has a professional look, I am all for it.

martijnende commented 5 years ago

Example: markdown.pdf

jpampuero commented 5 years ago

Looks good overall. Can margins be adjusted (bit wider)? Can one add page numbers, table of contents and page breaks between chapters?

martijnende commented 5 years ago

Not sure. I generated this PDF by simply copy/pasting the raw MD code into an online PDF generator. I will need to look into it further