include background information

[axd1967]

hello,

your pages are hugely interesting, to the point you could consider including them as a documentation source for the program.

as example, I've forked and created a first page here: https://github.com/axd1967/JAERO/blob/contrib/doc/doc/README.md

an alternative could be the wiki, but the advantage of including the doc is that the doc can nicely evolve together with code evolutions, while the wiki - even if it is also a Git repository - is independent.

if you like the idea, I can add the other hda1/ pages and send you a pull request, or if you prefer, I will drop the fork.

maybe a few more suggestions? I guess you are aware of these, yet allow me to suggest them:

• consider using this repo as your main page (instead of http://jontio.zapto.org/hda1/jaero.html); Git gives you the advantage that you can very easily - almost trivially - keep your own copy and the GitHub copy in sync. inconvenience of Markdown is maybe less nice page layout options. (and there is also github.io if you want a more website-like look.)
• don't bother presenting download links (see bottom of your page) - just point visitors to https://github.com/jontio/JAERO/releases, where they can find release history, executables and source code (otherwise you also need to keep that download section on your page in sync too).

rgds

-alex-

(FYI, I use PyCharm as Markdown editor)

(and I wrote this before stumbling over your http://jontio.zapto.org/software-and-hardware/webpagesetup.html ;-) )

[jontio]

Hi Alex,

Thanks for the ideas. Documentation with the source sounds reasonable. I like writing using my jontio.zapto.org website as I do things so divergence between the documentation in the source and my web site could be a problem as well as the extra work required updating two places were documentation resides.

I was always hoping that people would add pages to the wiki to create documentation but that hasn’t happened yet. I like the wiki idea as then people can easily add and change things without me.

I think http://jontio.zapto.org/hda1/jaero.html reads more like a log and something more “getting started” manual like might be more appropriate to include in the source repository.

However, due to personal circumstances I won’t be working on my website, documentation or JAERO for a few months at least.

Cheers,

Jonti

From: alex [mailto:notifications@github.com]
Sent: Thursday, 5 May 2016 9:55 p.m.
To: jontio/JAERO
Subject: [jontio/JAERO] include background information (#8)

hello,

your pages http://jontio.zapto.org/hda1/jaero.html are hugely interesting, to the point you could consider including them as a documentation source for the program.

as example, I've forked and created a first page here: https://github.com/axd1967/JAERO/blob/contrib/doc/doc/README.md

an alternative could be the wiki, but the advantage of including the doc is that the doc can nicely evolve together with code evolutions, while the wiki - even if it is also a Git repository - is independent.

if you like the idea, I can add the other hda1/ pages and send you a pull request, or if you prefer, I will drop the fork.

maybe a few more suggestions? I guess you are aware of these, yet allow me to suggest them:

• consider using this repo as your main page (instead of http://jontio.zapto.org/hda1/jaero.html); Git gives you the advantage that you can very easily - almost trivially - keep your own copy and the GitHub copy in sync. inconvenience of Markdown is maybe less nice page layout options. (and there is also github.io if you want a more website-like look.)
• don't bother presenting download links (see bottom of your page) - just point visitors to https://github.com/jontio/JAERO/releases, where they can find release history, executables and source code (otherwise you also need to keep that download section on your page in sync too).

rgds

-alex-

(FYI, I use PyCharm as Markdown editor)

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub #8 https://github.com/notifications/beacon/ANCOA8qJDyLD6tARl10n1SgauZ_akiu6ks5p-b6CgaJpZM4IX5Ly.gif

[axd1967]

hello @jontio

(BTW, there is no big difference between a wiki and normal pages - except maybe that the wiki allows for more easy diffing.)

IMHO I don't think the wiki will take off as a crowdsourced place to gather documentation.

And I suspect that - unless there is much activity around your app - a "getting started" manual will not materialise (one reason being it needs time, and you already indicated that would be an issue, so someone else needs to take that initiative). Just keeping the repo up-to-date with your findings make sit easier for others to get those changes (and discover the diffs) via git pull - a kind of (slightly more expensive) RSS/mailing list. But again, you already have tools and website, so I understand the choice is not easy.

I'll leave the fork for now, maybe it will generate more ideas; please contact/mention me if you want me to remove it.

rgds,
-alex-