Link in README.md to development reference broken
Created by: napcae
All development is done in feature branches so that the master branch is kept as stable as possible. If you would like to contribute, please refer to the relevant documentation.
there is no link, where should it link to? https://github.com/aerofoil/man ?
Imported comments:
By ke7ofi on 2014-06-19 16:33:47 UTC
ι 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?
By tomswartz07 on 2014-06-23 11:58:44 UTC
@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.
By ke7ofi on 2014-06-24 01:16:52 UTC
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?
By napcae on 2014-06-24 06:13:39 UTC
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.
By tomswartz07 on 2014-06-24 12:21:15 UTC
@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.
By napcae on 2014-06-24 13:39:47 UTC
@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.
By tomswartz07 on 2014-06-24 13:43:20 UTC
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 notifications@github.com 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 https://github.com/aerofoil/deb/issues/4#issuecomment-46971534.