Empathy List Archives

discuss@lists.openscad.org

OpenSCAD general discussion Mailing-list

Re: [OpenSCAD] Better format for documentation

MichaelAtOz

Wed, Mar 16, 2016 11:43 PM

gingerbeardman wrote

I appreciate that wiki-based documentation is great for a number of
reasons, such as being editable and visible to anybody.

But I wondered if there was a better formats or destination for the
documentation? Perhaps github itself? The benefits I am foreseeing are
export or reuse in documentation viewing apps such as Dash:
https://kapeli.com/dash

I don't mind getting involved in this effort.

Thoughts appreciated!

Bump. As it didn't make it to the mailing list.

Admin - PM me if you need anything, or if I've done something stupid...

Unless specifically shown otherwise above, my contribution is in the Public Domain; to the extent possible under law, I have waived all copyright and related or neighbouring rights to this work. Obviously inclusion of works of previous authors is not included in the above.

The TPP is no simple “trade agreement.” Fight it! http://www.ourfairdeal.org/ time is running out!

View this message in context: http://forum.openscad.org/Better-format-for-documentation-tp16503p16505.html
Sent from the OpenSCAD mailing list archive at Nabble.com.

gingerbeardman wrote > I appreciate that wiki-based documentation is great for a number of > reasons, such as being editable and visible to anybody. > > But I wondered if there was a better formats or destination for the > documentation? Perhaps github itself? The benefits I am foreseeing are > export or reuse in documentation viewing apps such as Dash: > https://kapeli.com/dash > > I don't mind getting involved in this effort. > > Thoughts appreciated! Bump. As it didn't make it to the mailing list. ----- Admin - PM me if you need anything, or if I've done something stupid... Unless specifically shown otherwise above, my contribution is in the Public Domain; to the extent possible under law, I have waived all copyright and related or neighbouring rights to this work. Obviously inclusion of works of previous authors is not included in the above. The TPP is no simple “trade agreement.” Fight it! http://www.ourfairdeal.org/ time is running out! -- View this message in context: http://forum.openscad.org/Better-format-for-documentation-tp16503p16505.html Sent from the OpenSCAD mailing list archive at Nabble.com.

Torsten Paul

Thu, Mar 17, 2016 12:46 AM

gingerbeardman wrote

While github would allow a more flexible way of storing and generating
documentation, it also (in my opinion at least) creates a much higher
barrier for people adding/fixing things in the documentation.
I don't have data that can really proof this assumption, but looking
at the history of Wiki changes, I do think it's true.

That mostly applies to the user documentation, something like an
additional (automatically from source generated?) documentation for
the language features would be nice too. There was some discussion
about tools that could be used for this type of documentation
(applies to both the C++ application code itself and also to
libraries/tutorials/examples written as scad scripts).

All that said, if there are other options, it makes sense to have a
look if they can help improving the documentation and/or access to
the it.
Dash seems limited to the Apple ecosystem, but maybe there are more
portable tools that could be used too (Zeal?).

Wikibooks has an API to export the raw data, so it would be possible
to use it as source. This would require some effort to unify and limit
the usage of Wiki markup features. But something like that would be
needed when migrating to a different storage too.

In addition there's already a tool for extracting the manual as
HTML which still waits to be integrated somehow into the build
process so the pages could be used as off-line documentation.
http://forum.openscad.org/Use-openscad-offliner-for-offline-documentation-td13096.html#a13131

ciao,
Torsten.

gingerbeardman wrote > But I wondered if there was a better formats or destination for the > documentation? Perhaps github itself? The benefits I am foreseeing are > export or reuse in documentation viewing apps such as Dash: > https://kapeli.com/dash > While github would allow a more flexible way of storing and generating documentation, it also (in my opinion at least) creates a much higher barrier for people adding/fixing things in the documentation. I don't have data that can really proof this assumption, but looking at the history of Wiki changes, I do think it's true. That mostly applies to the user documentation, something like an additional (automatically from source generated?) documentation for the language features would be nice too. There was some discussion about tools that could be used for this type of documentation (applies to both the C++ application code itself and also to libraries/tutorials/examples written as scad scripts). All that said, if there are other options, it makes sense to have a look if they can help improving the documentation and/or access to the it. Dash seems limited to the Apple ecosystem, but maybe there are more portable tools that could be used too (Zeal?). Wikibooks has an API to export the raw data, so it would be possible to use it as source. This would require some effort to unify and limit the usage of Wiki markup features. But something like that would be needed when migrating to a different storage too. In addition there's already a tool for extracting the manual as HTML which still waits to be integrated somehow into the build process so the pages could be used as off-line documentation. http://forum.openscad.org/Use-openscad-offliner-for-offline-documentation-td13096.html#a13131 ciao, Torsten.