Link in README.md to development reference broken about deb HOT 7 OPEN

ι left that link empty because it we haven’t decided where to put the bulk of our documentation. There are a few options.

• plaintext manpage-style documentation
• Markdown compiled by GitHub
• Markdown compiled by Jekyll

I like the idea of having the man repo in Markdown and somehow compiling from man to aerofoil.github.io, but I’m not sure how we’d do that.

As the semi-official documentation guy, what’s your opinion, @tomswartz07?

from deb.

@ke7ofi sorry for the delay. Summer vacation 😄

I'm a bit confused as to the end goal.

What types of things would be held in the documentation, aside from the contribution guidelines?

I'm not too concerned about what syntax it's written in; we could use pandoc to convert it to whatever format is needed after the fact.

It should be fairly easy to set up a gh-pages repo to create a landing page for the site.
However, such a landing page would be more useful as a way to get people to use the project or drum up interest, not to outline development rules.
Of course, we could have a minor blurb on the site directing developers, but the main focus should be to get users actually using it.

from deb.

The end-user focus is something to keep in mind. How do you think that
we can start moving in that direction?

On the IRC channel, @napcae suggested that we put most of the
documentation in the site's repository. I'd like to keep a separate repo
for docs for purposes of appropriate categorisation, but it's a less
convenient way of doing things. Do you think that either is a better way
of doing things?

from deb.

On the subject of the format: I think we can keep it that way, that the manual has it's own repo. I'm working on include the man repository as a submodule. So if we keep writing the manual in markdown(I also think that's the most versatile format/syntax), jekyll can just compile/convert it to html.

from deb.

@ke7ofi I think the easiest way to get started for 'user-facing' site is to create a repo exclusively for the gh-pages (aerofoil.github.io) site.
From there we could build it out.

In regards to a starting point, perhaps it would be easiest to start with an already-OSS gh-pages repo and customize it from there? Git for Windows has a pretty attractive landing page.

After the landing page, we could use jekyll to build out the other pages from markdown, as @napcae suggested.

from deb.

@tomswartz07 either I'm missing something or you overlooked that there already is a gh-pages site.
There is also a branch called doc_submodule where the "man" repo is included as a submodule. So writing the documentation in markdown will be compiled by jekyll into html.

from deb.

Oh, my mistake!

Completely overlooked that.
Carry on then!

Thomas Swartz

No trees were killed to send this message, but a large number of electrons
were terribly inconvenienced.

On Tue, Jun 24, 2014 at 9:39 AM, napcae [email protected] wrote:

@tomswartz07 https://github.com/tomswartz07 either I'm missing
something or you overlooked that there already is a gh-pages site
https://github.com/aerofoil/aerofoil.github.io.
There is also a branch called doc_submodule
https://github.com/aerofoil/aerofoil.github.io/tree/doc_submodule where
the "man" repo is included as a submodule. So writing the documentation in
markdown will be compiled by jekyll into html.

—
Reply to this email directly or view it on GitHub
#4 (comment).

from deb.