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, jart3@verizon.net wrote:

On 07/06/2015 08:06 PM, doug moen wrote:

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.

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).

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.

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.

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 Torsten.Paul@gmx.de:

On 07/06/2015 09:33 PM, Miro Hrončok wrote:

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.

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...

...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.

Torsten wrote:

The current user manual is currently missing important information. It

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:
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual

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:
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/The_OpenSCAD_Language

On 6 July 2015 at 14:44, Torsten Paul Torsten.Paul@gmx.de wrote:

On 07/06/2015 10:53 PM, doug moen wrote:

Yep, that's what I'm looking at too.

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.

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

$  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.

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 Torsten.Paul@gmx.de wrote:

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 runsun@gmail.com wrote: