Documentation framework

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

Documentation framework

nuest
Hi guys!

I started working on a contribute.md (see [1]) and was wondering what
your opinions are on a suitable documentation framework. At this point I
don't see myself contributing large amounts of code but I could help
with documentation etc.

So my question is how we will create documentation, particularly user
documentation and examples.

I like readthedocs [2] (uses Sphinx and would do the hosting for us),
but the more experienced JS devs might have a better understanding what
works well. Maybe this lists/blog posts [3] gives us a starting points
for discussion.

Will we use inline documentation and/or different systems (inline for
API doc, GitHub wiki for examples)?

Please share your experiences!
IMHO we should pick something that the current developers are
comfortable with.


Somehow related: How about a landing page for the project base on
GitHub-pages?


Best regards,
Daniel

[1] https://github.com/OSGeo/ows.js/issues/2
[2] https://readthedocs.org/
[3]
http://www.lsauer.com/2013/05/javascript-documentation-generator.html 
and http://dailyjs.com/2011/01/13/framework-part-46/ and
http://blog.fusioncharts.com/2013/12/jsdoc-vs-yuidoc-vs-doxx-vs-docco-choosing-a-javascript-documentation-generator/

--
Daniel Nüst
52°North Initiative for Geospatial Open Source Software GmbH
Martin-Luther-King-Weg 24
48155 Münster, Germany
E-Mail: [hidden email]
Fon: +49-(0)-251–396371-36
Fax: +49-(0)-251–396371-11

http://52north.org/
Twitter: @FiveTwoN

General Managers: Dr. Albert Remke, Dr. Andreas Wytzisk
Local Court Muenster HRB 10849
_______________________________________________
owsjs mailing list
[hidden email]
http://lists.osgeo.org/cgi-bin/mailman/listinfo/owsjs
Reply | Threaded
Open this post in threaded view
|

Re: Documentation framework

Tom Kralidis


On Mon, 16 Mar 2015, Daniel Nüst wrote:

> Date: Mon, 16 Mar 2015 11:18:21 +0100
> From: Daniel Nüst <[hidden email]>
> To: [hidden email]
> Subject: [ows.js] Documentation framework
>
> Hi guys!
>
> I started working on a contribute.md (see [1]) and was wondering what
> your opinions are on a suitable documentation framework. At this point I
> don't see myself contributing large amounts of code but I could help
> with documentation etc.
>

This would be awesome!

> So my question is how we will create documentation, particularly user
> documentation and examples.
>
> I like readthedocs [2] (uses Sphinx and would do the hosting for us),
> but the more experienced JS devs might have a better understanding what
> works well. Maybe this lists/blog posts [3] gives us a starting points
> for discussion.
>
> Will we use inline documentation and/or different systems (inline for
> API doc, GitHub wiki for examples)?
>
> Please share your experiences!
> IMHO we should pick something that the current developers are
> comfortable with.
>

Using sphinx with readthedocs for documentation has worked for me in
the past.  Are there alternatives which are friendly for JavaScript
devs?

For examples we may or may not require a deployment given accessing
content via JS on other servers.

>
> Somehow related: How about a landing page for the project base on
> GitHub-pages?
>

+1.  I'll set this up once we have a doc setup.

>
> Best regards,
> Daniel
>
> [1] https://github.com/OSGeo/ows.js/issues/2
> [2] https://readthedocs.org/
> [3]
> http://www.lsauer.com/2013/05/javascript-documentation-generator.html 
> and http://dailyjs.com/2011/01/13/framework-part-46/ and
> http://blog.fusioncharts.com/2013/12/jsdoc-vs-yuidoc-vs-doxx-vs-docco-choosing-a-javascript-documentation-generator/
>
> --
> Daniel Nüst
> 52°North Initiative for Geospatial Open Source Software GmbH
> Martin-Luther-King-Weg 24
> 48155 Münster, Germany
> E-Mail: [hidden email]
> Fon: +49-(0)-251–396371-36
> Fax: +49-(0)-251–396371-11
>
> http://52north.org/
> Twitter: @FiveTwoN
>
> General Managers: Dr. Albert Remke, Dr. Andreas Wytzisk
> Local Court Muenster HRB 10849
> _______________________________________________
> owsjs mailing list
> [hidden email]
> http://lists.osgeo.org/cgi-bin/mailman/listinfo/owsjs
>
_______________________________________________
owsjs mailing list
[hidden email]
http://lists.osgeo.org/cgi-bin/mailman/listinfo/owsjs
Reply | Threaded
Open this post in threaded view
|

Re: Documentation framework

Juan Manuel Vicente
I think Markdown can do the work. It is simple and a good number of JS devs are using it (or know it). Jsonix repo use Wiki pages with Markdown, but maybe will be better use Github-pages with Markdown.


On Mon, Mar 16, 2015 at 7:47 AM, Tom Kralidis <[hidden email]> wrote:


On Mon, 16 Mar 2015, Daniel Nüst wrote:

Date: Mon, 16 Mar 2015 11:18:21 +0100
From: Daniel Nüst <[hidden email]>
To: [hidden email]
Subject: [ows.js] Documentation framework

Hi guys!

I started working on a contribute.md (see [1]) and was wondering what your opinions are on a suitable documentation framework. At this point I don't see myself contributing large amounts of code but I could help with documentation etc.


This would be awesome!

So my question is how we will create documentation, particularly user documentation and examples.

I like readthedocs [2] (uses Sphinx and would do the hosting for us), but the more experienced JS devs might have a better understanding what works well. Maybe this lists/blog posts [3] gives us a starting points for discussion.

Will we use inline documentation and/or different systems (inline for API doc, GitHub wiki for examples)?

Please share your experiences!
IMHO we should pick something that the current developers are comfortable with.


Using sphinx with readthedocs for documentation has worked for me in
the past.  Are there alternatives which are friendly for JavaScript
devs?

For examples we may or may not require a deployment given accessing
content via JS on other servers.


Somehow related: How about a landing page for the project base on GitHub-pages?


+1.  I'll set this up once we have a doc setup.



Best regards,
Daniel

[1] https://github.com/OSGeo/ows.js/issues/2
[2] https://readthedocs.org/
[3] http://www.lsauer.com/2013/05/javascript-documentation-generator.html and http://dailyjs.com/2011/01/13/framework-part-46/ and http://blog.fusioncharts.com/2013/12/jsdoc-vs-yuidoc-vs-doxx-vs-docco-choosing-a-javascript-documentation-generator/

--
Daniel Nüst
52°North Initiative for Geospatial Open Source Software GmbH
Martin-Luther-King-Weg 24
48155 Münster, Germany
E-Mail: [hidden email]
Fon: <a href="tel:%2B49-%280%29-251%E2%80%93396371-36" value="+4925139637136" target="_blank">+49-(0)-251–396371-36
Fax: <a href="tel:%2B49-%280%29-251%E2%80%93396371-11" value="+4925139637111" target="_blank">+49-(0)-251–396371-11

http://52north.org/
Twitter: @FiveTwoN

General Managers: Dr. Albert Remke, Dr. Andreas Wytzisk
Local Court Muenster HRB 10849
_______________________________________________
owsjs mailing list
[hidden email]
http://lists.osgeo.org/cgi-bin/mailman/listinfo/owsjs

_______________________________________________
owsjs mailing list
[hidden email]
http://lists.osgeo.org/cgi-bin/mailman/listinfo/owsjs


_______________________________________________
owsjs mailing list
[hidden email]
http://lists.osgeo.org/cgi-bin/mailman/listinfo/owsjs