Ok now I would like to go back to the basics, i.e. good pages, structure and style.
I think it was already agreed also in other posts that, to have a consistent documentation, we need rules.
I know everybody is scared of rules, either on imposing them (who am I to dictate rules for the others) or to follow them (how boring.. read them, learn them, abide to).
However, also I saw many posts of puzzled contributors asking some guidance on how to do this or that. Rules help in this respect, i.e. you have some hint on how to provide your content without breaking up what has already been done.
The other major benefit is to have a common look&feel and a common structure, leading eventually to a good documentation.
So I went on collecting all the information I could about either what has already been agreed or the best practices followed in the already existing body of documentation, and used the page
WikiPages to provide the famous rules.
However, I am myself scared of imposing them, not wanting to bluntly step on the feet of so many people contributing to this valid project - I would like to have a full review by all of you before, if it is the case in the end, linking officially this page to the
Help FreeCAD page. Remember anyway that rules are good for the 95% of the cases, but this does not mean that you cannot break them; but you must have a good reason to do so.
Please mind that in
WikiPages I am giving rules mainly for style and structure, not for content. Good content is another topic, but I think that most of the content is already good, and must be organized accordingly. Content anyway can be the topic of another post (i.e. as Normand was pointing out, how far you should go in describing a workbench usage / model / etc.), not to mix feedback here.
The main philosophy that stressed in
WikiPages is using templates whenever possible to style the pages. This is in line with the Wiki approach, where people should be more focused in providing a content and less to the markup (so the learning curve is shorter). Decoupling style from content is of course the same idea behind CSS; but in this case standard editors don't (and should not) touch the CSS, nor should use html tags.
Using templates to style the pages (as already extensively done) makes also it easy to postpone the decision about the graphical aspect of key strokes, menus, etc. that can also depend, as we know, from personal taste. But once everything is template, of course you just change the template to update everything in one shot. This is not true instead if we start using simple bold (wiki ''') for keystrokes (as myself wrongly proposed here - but I was thinking about the final render, not how to get there).
I also made arbitrary reference to two pages that IMHO are very good (and would need minimum editing to be fully in line with the
WikiPages recommendations.
I would also
deprecate the
Std ViewScreenShot page instead; not to blame anybody, but I think this is far (in style!) from the latest trend as per
GuiCommand model (i.e. headers are very small, 'synopsis' is really worst than 'description', etc.)
Moreover, I added some recommendations that are again somehow arbitrary, e.g. in the size of the pictures; but I saw too many pages with pictures one after the other with completely different widths, as well as not fitting in most (smaller) monitors, let alone in a printed (pdf) documentation.
I left a second section with the original brainstorming (minus what I mainly already absorbed as rules in the first section). This could be left there, or better, since can confuse new want-to-be editors, moved either to the Talk: of the same page or to another page completely.
So in a nutshell: please review
WikiPages and post your comments under this topic.
Thank you
Ciao
Enrico