feature request: offline documentation

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

feature request: offline documentation

John Tucker
Can I interject a thought regarding the discussion regarding documentation?

I'm using Debian Linux and they're about 2 light years behind in their
version of OpenScad. I realize that the people now working on methods to
improve distributing documentation cannot go back but, I think that having the
appropriate documentation for the release you have, distributed with
the OpenScad distribution itself, is desirable.

If someone wants to peruse features available  on newer releases they
can download from or read on the Wiki.

Jack Tucker


_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
Reply | Threaded
Open this post in threaded view
|

Re: feature request: offline documentation

doug.moen
In principle, versioned documentation is a good idea. I wonder if we can support that in our process.

If we are going to continue with making the documentation wiki-editable, then we would need to version the documentation in the wiki. Which sounds good, since the current user manual is cluttered with references to obsolete features, and "this only works in version X" annotations. If the pace of innovation picks up, or as time goes on, the clutter gets worse.

But, we'll need to clone the entire user manual at each release, on the wiki. The downside is that edits to one version of the user manual aren't automatically propagated to other versions. Somebody would have to periodically review edits to each version and decide whether to propagate those edits to other versions. Who will do this? Or maybe old versions of the user manual are frozen and made non-editable? Maybe we can generate versions of the user manual for older releases by retrieving versions from the wiki history? Again, who will volunteer to do this?

The current user manual is currently missing important information. It doesn't document user defined functions, or the new text feature. So we certainly could be maintaining it a lot better.

On 6 July 2015 at 12:59, <[hidden email]> wrote:
Can I interject a thought regarding the discussion regarding documentation?

I'm using Debian Linux and they're about 2 light years behind in their
version of OpenScad. I realize that the people now working on methods to
improve distributing documentation cannot go back but, I think that having the
appropriate documentation for the release you have, distributed with
the OpenScad distribution itself, is desirable.

If someone wants to peruse features available  on newer releases they
can download from or read on the Wiki.

Jack Tucker


_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org



_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
tp3
Reply | Threaded
Open this post in threaded view
|

Re: feature request: offline documentation

tp3
On 07/06/2015 08:06 PM, doug moen wrote:
> If we are going to continue with making the documentation wiki-editable,
> then we would need to version the documentation in the wiki. Which sounds
> good, since the current user manual is cluttered with references to
> obsolete features, and "this only works in version X" annotations. If the
> pace of innovation picks up, or as time goes on, the clutter gets worse.
>
The clutter gets worse if it's not maintained. That's not really related
to the technical solution but the time spend on the documentation.

What obsolete features are still in there? If you have a pointer to that,
I'll try to clean that up.

> But, we'll need to clone the entire user manual at each release, on the
> wiki. The downside is that edits to one version of the user manual aren't
> automatically propagated to other versions. Somebody would have to
> periodically review edits to each version and decide whether to propagate
> those edits to other versions.
 >
That would be a nice and clean solution, but I think that would only
work if there's a documentation team of multiple people working on that
as Wikibooks does not seem to support versioning. Doing all that manually
is going to be a huge amount of work. I don't see that currently so I'd
suggest to not make it very complicated and live with some of drawbacks
(e.g. some of the "this needs version xxxx" markers).

> Who will do this? Or maybe old versions of the user manual are frozen
 > and made non-editable?
 >
Wikibooks already has the normal review stuff where someone needs to
accept changes. I do have the Reviewer role now so I'm going though
the changes from time to time (there are others helping with that too).
But of cause that's not really related to OpenSCAD versions.
Apart from that "reviewed" state I've not yet seen a way to freeze
some content.

> The current user manual is currently missing important information. It
> doesn't document user defined functions, or the new text feature. So we
> certainly could be maintaining it a lot better.
>
Only that separate Print_version is missing that information (links)

https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Text

https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/User-Defined_Functions

But if you see missing info, please post a pointer.

ciao,
   Torsten.


_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
-- Torsten
Reply | Threaded
Open this post in threaded view
|

Re: feature request: offline documentation

Miro Hrončok
One possible solution to keep the docs maintained and up to date is to
keep the documentation where the code is.

Is put linear_extrude() doc in the very same file where the logic is
defined. Whenever someone changes/add/removes a feature, they are
supposed to change the doc in the same file and the same PR (and even
better in the same commit).

Than, for any version, related documentation can be exported.

The downside is, it would no longer be so easy to contribute to do the
documentation, as it is on the wiki now.

Miro Hrončok

Telefon: +420777974800


2015-07-06 20:44 GMT+02:00 Torsten Paul <[hidden email]>:

> On 07/06/2015 08:06 PM, doug moen wrote:
>>
>> If we are going to continue with making the documentation wiki-editable,
>> then we would need to version the documentation in the wiki. Which sounds
>> good, since the current user manual is cluttered with references to
>> obsolete features, and "this only works in version X" annotations. If the
>> pace of innovation picks up, or as time goes on, the clutter gets worse.
>>
> The clutter gets worse if it's not maintained. That's not really related
> to the technical solution but the time spend on the documentation.
>
> What obsolete features are still in there? If you have a pointer to that,
> I'll try to clean that up.
>
>> But, we'll need to clone the entire user manual at each release, on the
>> wiki. The downside is that edits to one version of the user manual aren't
>> automatically propagated to other versions. Somebody would have to
>> periodically review edits to each version and decide whether to propagate
>> those edits to other versions.
>
>>
> That would be a nice and clean solution, but I think that would only
> work if there's a documentation team of multiple people working on that
> as Wikibooks does not seem to support versioning. Doing all that manually
> is going to be a huge amount of work. I don't see that currently so I'd
> suggest to not make it very complicated and live with some of drawbacks
> (e.g. some of the "this needs version xxxx" markers).
>
>> Who will do this? Or maybe old versions of the user manual are frozen
>
>> and made non-editable?
>>
> Wikibooks already has the normal review stuff where someone needs to
> accept changes. I do have the Reviewer role now so I'm going though
> the changes from time to time (there are others helping with that too).
> But of cause that's not really related to OpenSCAD versions.
> Apart from that "reviewed" state I've not yet seen a way to freeze
> some content.
>
>> The current user manual is currently missing important information. It
>> doesn't document user defined functions, or the new text feature. So we
>> certainly could be maintaining it a lot better.
>>
> Only that separate Print_version is missing that information (links)
>
> https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Text
>
> https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/User-Defined_Functions
>
> But if you see missing info, please post a pointer.
>
> ciao,
>   Torsten.
>
>
>
> _______________________________________________
> OpenSCAD mailing list
> [hidden email]
> http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org

_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
tp3
Reply | Threaded
Open this post in threaded view
|

Re: feature request: offline documentation

tp3
On 07/06/2015 09:33 PM, Miro Hrončok wrote:
> One possible solution to keep the docs maintained and up to date is to
> keep the documentation where the code is.
>
> Is put linear_extrude() doc in the very same file where the logic is
> defined. Whenever someone changes/add/removes a feature, they are
> supposed to change the doc in the same file and the same PR (and even
> better in the same commit).
>
Yes, for technical docs that's perfect, although it's currently
not really done. I don't see how that would work for the user
documentation which is not related to some specific source file
or function and also includes images.

> Than, for any version, related documentation can be exported.
>
Yep, right now I don't see how we could get this in an easy
way with Wikibooks, it would be easy with the documentation
stored in the git repo, but...

> The downside is, it would no longer be so easy to contribute to
 > do the documentation, as it is on the wiki now.
 >
...this downside is much bigger in my opinion than the technical
benefits github can give. Having written some (small) parts of
the manual for the stuff I've implemented, I really value the
contributions that are coming in on the Wiki pages, even the
tiny ones that are just adding a note to clarify special cases
or tidy up the language.

ciao,
   Torsten.


_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
-- Torsten
Reply | Threaded
Open this post in threaded view
|

Re: feature request: offline documentation

doug.moen
In reply to this post by tp3
Torsten wrote:

The current user manual is currently missing important information. It
doesn't document user defined functions, or the new text feature. So we
certainly could be maintaining it a lot better.

Only that separate Print_version is missing that information (links)

https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Text

https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/User-Defined_Functions

-----------------
This nothing to do with a "separate Print_version".

The OpenSCAD user manual is located here:

As far as I have always known, that *is* the user manual.
Now you are showing me links to apparently secret parts of the user manual that document text and user defined functions.
How does a user discover these links, since they are not referenced by the user manual?

Maybe the answer to that isn't important.
The user manual should be updated so that it links to all of the sections in the user manual.
Since user defined functions and text are part of the language, these sections should be linked to by:



On 6 July 2015 at 14:44, Torsten Paul <[hidden email]> wrote:
On 07/06/2015 08:06 PM, doug moen wrote:
If we are going to continue with making the documentation wiki-editable,
then we would need to version the documentation in the wiki. Which sounds
good, since the current user manual is cluttered with references to
obsolete features, and "this only works in version X" annotations. If the
pace of innovation picks up, or as time goes on, the clutter gets worse.

The clutter gets worse if it's not maintained. That's not really related
to the technical solution but the time spend on the documentation.

What obsolete features are still in there? If you have a pointer to that,
I'll try to clean that up.

But, we'll need to clone the entire user manual at each release, on the
wiki. The downside is that edits to one version of the user manual aren't
automatically propagated to other versions. Somebody would have to
periodically review edits to each version and decide whether to propagate
those edits to other versions.
>
That would be a nice and clean solution, but I think that would only
work if there's a documentation team of multiple people working on that
as Wikibooks does not seem to support versioning. Doing all that manually
is going to be a huge amount of work. I don't see that currently so I'd
suggest to not make it very complicated and live with some of drawbacks
(e.g. some of the "this needs version xxxx" markers).

Who will do this? Or maybe old versions of the user manual are frozen
> and made non-editable?
>
Wikibooks already has the normal review stuff where someone needs to
accept changes. I do have the Reviewer role now so I'm going though
the changes from time to time (there are others helping with that too).
But of cause that's not really related to OpenSCAD versions.
Apart from that "reviewed" state I've not yet seen a way to freeze
some content.

The current user manual is currently missing important information. It
doesn't document user defined functions, or the new text feature. So we
certainly could be maintaining it a lot better.

Only that separate Print_version is missing that information (links)

https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Text

https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/User-Defined_Functions

But if you see missing info, please post a pointer.

ciao,
  Torsten.



_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org



_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
tp3
Reply | Threaded
Open this post in threaded view
|

Re: feature request: offline documentation

tp3
On 07/06/2015 10:53 PM, doug moen wrote:
> The OpenSCAD user manual is located here:
> https://en.wikibooks.org/wiki/OpenSCAD_User_Manual
>
> As far as I have always known, that *is* the user manual.
 >
Yep, that's what I'm looking at too.

> Now you are showing me links to apparently secret parts of the user manual
> that document text and user defined functions.
> How does a user discover these links, since they are not referenced by the
> user manual?
>
I have no idea what's going on then. Those links are not
secret, and I see both on the main page (List-Comprehensions
is 3.6 and Text is 4.2.) even when not logged into Wikibooks.

There could be a difference if something new is added as I
think it defaults to the reviewed version but in that case
an additional bar in the top mentions there are pending
changes (which is currently not the case for the main page).

ciao,
   Torsten.


_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
-- Torsten
Reply | Threaded
Open this post in threaded view
|

Re: feature request: offline documentation

runsun
In reply to this post by Miro Hrončok
This is the approach that I like. My lib OpenScad_DocTest (see links in the signature) is an attempt to make in-file docs (and tests) possible  

But I can picture that it won't be popular  'cos jamming codes with full docs doesn't seem to be a common practice.

Miro Hrončok wrote
One possible solution to keep the docs maintained and up to date is to
keep the documentation where the code is.

Is put linear_extrude() doc in the very same file where the logic is
defined. Whenever someone changes/add/removes a feature, they are
supposed to change the doc in the same file and the same PR (and even
better in the same commit).
$ Runsun Pan, PhD
$ libs: scadx, doctest, faces(git), offline doc(git), runscad.py(2,git), editor of choice: CudaText ( OpenSCAD lexer); $ Tips; $ Snippets
Reply | Threaded
Open this post in threaded view
|

Re: feature request: offline documentation

doug.moen
In reply to this post by tp3
Okay, now I see the link to User-Defined Functions at 3.12.

What has always messed me up in the past is that I never read that table of contents, I have always clicked on "3. The OpenSCAD Language", which opens a document which has its own table of contents, which is missing user-defined functions. I never realized that those two tables-of-contents were out of sync.

And yeah, now I see the link to Text in 4.2. I had always skipped past that section, assuming it was tutorial information that expanded on the language reference manual stuff in "3. The OpenSCAD Language". Now I see that the 2D primitives are missing from section 3. Weird. I've used circle, square and linear_extrude, but I've never seen the documentation for it before.

So it's mental blindness on my part, assuming that the documentation had a structure which it doesn't have. I thought the tables of contents were in sync across levels, and that section 3 documented the entire language.

On 6 July 2015 at 16:59, Torsten Paul <[hidden email]> wrote:
On 07/06/2015 10:53 PM, doug moen wrote:
The OpenSCAD user manual is located here:
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual

As far as I have always known, that *is* the user manual.
>
Yep, that's what I'm looking at too.

Now you are showing me links to apparently secret parts of the user manual
that document text and user defined functions.
How does a user discover these links, since they are not referenced by the
user manual?

I have no idea what's going on then. Those links are not
secret, and I see both on the main page (List-Comprehensions
is 3.6 and Text is 4.2.) even when not logged into Wikibooks.

There could be a difference if something new is added as I
think it defaults to the reviewed version but in that case
an additional bar in the top mentions there are pending
changes (which is currently not the case for the main page).


ciao,
  Torsten.


_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org



_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
Reply | Threaded
Open this post in threaded view
|

Re: feature request: offline documentation

doug.moen
In reply to this post by runsun
People who are good at writing documentation are often not the same people who are good at writing C++ code.

That said, I'll also note that I'm maintaining all the documentation for OpenSCAD2 in a github repository. Not in the repo's wiki, but in the repo itself. I can totally use a web browser for editing all of the documentation, pretty much the same thing as using a wiki.

I think the main issue is just that repos have a different model for permissions than a wiki. It's not enough to have a github login, you also need permission from the repo owner before you can directly edit documentation in a repo. Otherwise, your only option is to fork the repo, make changes, and submit a pull request, which is way more complicated and bureaucratic than editing a wiki. It's a bit much to impose that kind of process on the people who are good at writing documentation.

On 6 July 2015 at 17:28, runsun <[hidden email]> wrote:
This is the approach that I like. My lib OpenScad_DocTest (see links in the
signature) is an attempt to make in-file docs (and tests) possible

But I can picture that it won't be popular  'cos jamming codes with full
docs doesn't seem to be a common practice.


Miro Hrončok wrote
> One possible solution to keep the docs maintained and up to date is to
> keep the documentation where the code is.
>
> Is put linear_extrude() doc in the very same file where the logic is
> defined. Whenever someone changes/add/removes a feature, they are
> supposed to change the doc in the same file and the same PR (and even
> better in the same commit).





-----

$  Runsun Pan, PhD

$ -- OpenScad_DocTest: doc and unit test ( Github , Thingiverse  )

$ -- hash parameter model: here , here

$ -- Linux Mint 17.1 Rebecca x64  + OpenSCAD 2015.03.15/2015.04.01.nightly




--
View this message in context: http://forum.openscad.org/feature-request-offline-documentation-tp13068p13076.html
Sent from the OpenSCAD mailing list archive at Nabble.com.

_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org


_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
Reply | Threaded
Open this post in threaded view
|

Re: feature request: offline documentation

MichaelAtOz
Administrator
In reply to this post by tp3
tp3 wrote
On 07/06/2015 10:53 PM, doug moen wrote:
> The OpenSCAD user manual is located here:
> https://en.wikibooks.org/wiki/OpenSCAD_User_Manual
>
> As far as I have always known, that *is* the user manual.

I have no idea what's going on then. Those links are not
secret, and I see both on the main page (List-Comprehensions
is 3.6 and Text is 4.2.) even when not logged into Wikibooks.

There could be a difference if something new is added as I
think it defaults to the reviewed version but in that case
an additional bar in the top mentions there are pending
changes (which is currently not the case for the main page).
There is a way in wiki to replicate the content in an article inline another. I came across it a while ago, so will have to look for it again.
That way, things like the other pages which are not updated could be changed to drag in the main text from the main page rather than having a dup which is out of date.
Admin - email* me if you need anything, or if I've done something stupid...
* click on my MichaelAtOz label, there is a link to email me.

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.
Reply | Threaded
Open this post in threaded view
|

Re: feature request: offline documentation

MichaelAtOz
Administrator
I just added the hidden comment below to the main wiki page. Pretty self explainatory. I'll have a look at getting them back in sync in a while.


< !-- HEY!!!!!!!!!!!!!!!!!!!!         >>>>>>>>>>>>>>>>>>>>>READ THIS <<<<<<<<<<<<<<<<

If you intend to alter the structure of this or ADD new sections PLEASE note that similar changes are required in two other pages.

https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/The_OpenSCAD_Language  - a list of all the language as one large page
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Print_version - similar to the above, designed for printing.

Both these pages use transclusion* which basically lists the page links to pull other pages into the main page.
So if you add/change/reorganise/delete some pages here, please have a look at these other two pages and keep them in sync as appropriate to their function.

* https://en.wikipedia.org/wiki/Wikipedia:Transclusion

Thank You, MichaelAtOz.
-->
Admin - email* me if you need anything, or if I've done something stupid...
* click on my MichaelAtOz label, there is a link to email me.

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.