Comments (7)
ι 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.
Related Issues (2)
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from deb.