serially reading the Manual

[garya]

v0.18 (I pulled from 47fd9d3, built on free bsd), clicking the "Help" tab in the 3D panel shows the Manual as an option in the left hand column.
The Manual is supposed to be a more linear, book-like way of learning about FreeCAD. Clicking on the Manual link replaces the current contents with the Introduction page of the manual; opening in an external browser gives the same page in the browser.
Unfortunately, parts of the manual aren't navigated like a written document.
In particular, from the Introduction page, there is no <next> or <prev> link. One has to guess that the next link on the left, "What is FreeCAD?" is the appropriate next page.
There are three links at the bottom of the "What is FreeCAD" page, and it is unclear whether they are meant to be read in order or if they are supplementary information one will "eventually get to anyway" if proceeding linearly through the document.
If one proceeds to the "About FreeCAD" page, it has a <previous> link that goes to the "Online Help Startup" page, not the "What is FreeCAD" page.
Questions:
1. Are the above pages (Introduction => What is FreeCAD => About FreeCAD) supposed to read sequentially?
2. Are the issues above just errors, or a result of the fact they are generated from the wiki (are they?)?
3. If they are meant to be read sequentially, shouldn't "Read More" be an optional section which, if present, is always followed by a <next> ... <prev> navigation line?
4. How does one configure the nav bar with an empty <previous>? Or should the first page go to ... the FreeCAD Start page?
5. How does one configure the nav bar to reference the Index in the middle? Is that link generated on the fly?
6. I would suggest that in book format, there should also be a nav bar at the top of the page, so one can easily skip a page without scrolling to the bottom.

[Johnquicker]

Unfortunately, parts of the manual aren't navigated like a written document.
In particular, from the Introduction page, there is no <next> or <prev> link. One has to guess that the next link on the left, "What is FreeCAD?" is the appropriate next page.

Hi, Garya, I saw your point, and have the same feeling of bothering when having to scroll up and think a moment where I'm and figure out which link is the next page. I think it will be convenient to have the <next> and <prev> links.
I am planning to translate this manual into simplified Chinese and have done on some of the pages. I was informed that the pages translated early have been out of date, so I edit the translations.

• Will you edit the whole manual lately?
  @yorik has been seeking some native speaker to edit his texts, and I found your changes are what I will do with some Chinese text: making them more like what we say daily.
• Will you update this manual with FC version 0.18?
  I was surprised to see that it is still on version 0.16 since so many people said this manual was really needed and is awesome.

[yorik]

Hi,

Yes, prev and next links would be great. The manual was actually written as markdown pages on github, to be rendered by some platform like readthedocs or gitbook, which would take care of this. But since it migrated to the wiki, indeed the left menu is far from good. But indeed it's meant to become a book at some point, so it is fully sequential.

Feel free to improve things! There is a navbar already that can be used: https://www.freecadweb.org/wiki/Template:Docnav we could alter it so it can take a custom index page...
Example to use it: https://www.freecadweb.org/wiki/FreeCAD ... ing_Basics

4. How does one configure the nav bar with an empty <previous>? Or should the first page go to ... the FreeCAD Start page?
5. How does one configure the nav bar to reference the Index in the middle? Is that link generated on the fly?
6. I would suggest that in book format, there should also be a nav bar at the top of the page, so one can easily skip a page without scrolling to the bottom.

I would leave the first link empty, I believe it works... And yes, there could be one on top too

As for adapting he manual to 0.18, I think some parts should be fully redone... (TechDraw for example). That's not on my list, but it would be a good idea to start doing that.

[garya]

• Will you edit the whole manual lately?

@yorik has been seeking some native speaker to edit his texts, and I found your changes are what I will do with some Chinese text: making them more like what we say daily.

I have not edited the whole manual; only a few pages. I only recently started working my way through it as a way to learn FreeCAD, but then I had questions. I did not want to continue until those questions were answered. Yorik has answered them. I will try to continue as I have time. I have a <em>little</em> CAD experience, having made one part actually being used in manufacturing; but it is very little experience and I have only worked with two or three different workbenches. I have a some experience as a technical editor and as a software engineer.

• Will you update this manual with FC version 0.18?

Yes, when I change things I will use 0.18 as the discussion target. However, my 0.18 is not the most recent. I run freebsd and I have to update my personal port to get a more recent build. The process is different from a linux port so I don't do it very often.

[renatorivo]

There is a navbar already that can be used: https://www.freecadweb.org/wiki/Template:Docnav we could alter it so it can take a custom index page...

You can see the model https://www.freecadweb.org/wiki/Template:Docnav/it

[yorik]

You can see the model https://www.freecadweb.org/wiki/Template:Docnav/it

Yeah that's a good way to do it... Copy the docnav code into another template page, docnavmanual for example, and change the index

[garya]

There is a navbar already that can be used: https://www.freecadweb.org/wiki/Template:Docnav we could alter it so it can take a custom index page...

You can see the model https://www.freecadweb.org/wiki/Template:Docnav/it

There must be a little more to this than I am seeing.
I added this to the intro page:
{{Docnav|Online Help Startpage|What is FreeCAD}}
It correctly goes to the previous page, but the link to "What is FreeCAD" doesn't work.
What am I missing?
Is the Category in any way related to the Docnav?

[yorik]

I updated the https://www.freecadweb.org/wiki/Template:Docnav template so now it can take two more arguments to define the index.
I also updated https://www.freecadweb.org/wiki/Manual:Introduction to show how it works, have a look.
You must prefix the manual pages links with Manual: because they were created that way...

[garya]

I updated the https://www.freecadweb.org/wiki/Template:Docnav template so now it can take two more arguments to define the index.
I also updated https://www.freecadweb.org/wiki/Manual:Introduction to show how it works, have a look.
You must prefix the manual pages links with Manual: because they were created that way...

Great, thanks.
One more question:
Some pages have a category of Manual, some have a category of User Documentation, some have both, some have none.
Is there any good heuristic to deciding what categories a page should be in? Any list of current categories? Is there also a Reference category? If not, should there be? I would think all manual pages would be in both Manual and User Documentation, but maybe not. For example, where a regular workbench page is part of the manual, is it ok to mark it in category Manual? In which case it could be in both Reference and Manual. Or should the workbenches have a manual page separate from their reference page, i.e. one with more explanatory text and examples, and only link to the reference page for the wb? I hesitate to suggest an additional page, as it makes maintenance that much more difficult. One could put the additional example stuff at the end of the reference page.
Alternately, a manual page could be designed as a particularly sparse most-common-simple use type page that contains examples and points to the reference page as appropriate. But that becomes difficult -- my experience is any time there is something that needs additional explanation on a manual page, that aspect probably needs some words in the reference as well.

[yorik]

I think wiki categories are a "use them all" thing. If a certain page is relevant to a certain category, add it. Categories are not used to structure things in any way. They are just a "gathered view" of a group of pages. There is no problem in a page being part of many even contradictory categories. For example, I would imagine some pages could be in both user documentation and poweruser documentation.

About the links at the end of each manual pages, they are definitely not meant to be read sequentially, as they venture into the multiform realm of the wiki. I consider them as "do you want to know more?" things, that are fully optional and not needed in the manual itself.

One other thing is that the manual is big already. The pdf version has like more than 150 pages. This is a good size I think, it shouldn't grow much more otherwise it will loose its practicity for a newcomer. And it's a good exercise to try to condensate your thoughts into short, readable chapters. And also I always have the idea of publishing a printed version of the manual in mind