kicad-doc-devs team mailing list archive

[f.dos.santos@xxxxxxx]

Hi, 

Now that 5.1.6 is on its way I want to start fixing those pesky 

documentation issues which shows that our documentation is outdated 
for the next release. 
I'll start with the KiCad project manager, it's a short document but 
already has some annoying issues. I won't list them all here but will 
open an issue on gitlab for each of them. 

By the way, Nick, I'm interested in getting some permission on the issue 
tracker to be able, for example, to close this one : 
https://gitlab.com/kicad/services/kicad-doc/-/issues/772 


With our 2 branch model (master for development documentation dedicated 
mainly for writers and 5.1 for our current stable documentation mainly 
for translators), how are we managing fixes that concern both releases ? 

Do we fix issues in master in an iterative process and at a later date 
we cherry pick them into 5.1 and after that start translation work ? 

Or do we cherry pick them immediately after being commited into master ? 
This will defeat our purpose of having master being a moving target and 
stable branch to be the most stable for translation work. 
On the other hand introducing fixes as soon as possible will give plenty 
of time for translators to do their job. 


To be more practical, some examples in the project manager : 

1) https://docs.kicad-pcb.org/5.1.5/en/kicad/kicad.html#kicad_files_and_folders 

*.pro "containing a few parameters for the current project, including the component library list." 
With sym-lib-table, libraries are no longer in the .pro file 


2) https://docs.kicad-pcb.org/5.1.5/en/kicad/kicad.html#initialization_of_external_utilities 

Screenshot and menu instructions are outdated. 


3) https://docs.kicad-pcb.org/5.1.5/en/kicad/kicad.html#creating_a_new_project 

There is no need to manually create the project directory, it's already taken 
care of by KiCad. 


4) https://docs.kicad-pcb.org/5.1.5/en/kicad/kicad.html#top_toolbar 

Top toolbar doesn't show the "Open project directory in file explorer" icon 
and explanation shows a "Update and save the current project" that doesn't 
exists and lack the "Unarchive project files from zip archive" option. 


5) https://docs.kicad-pcb.org/5.1.5/en/kicad/kicad.html#template_locations 

This one needs confirmation from a developer. 


User templates directory are spelled "templates", I think it's a typo, in system 
templates it's just "template". 
Also KICAD_PTEMPLATES doesn't seem to work anymore, I wasn't able to show 
the third tab "Portable Templates". 


6) https://docs.kicad-pcb.org/5.1.5/en/kicad/kicad.html#creating_templates 

In Required File : "Due to font kerning, typically 7 or 8 characters can be 
displayed", doesn't seem to be the case anymore, for me 30 characters or so 
are successfully displayed. 


So take the shoes of someone fixing one of those issues, what our workflow 
should be to fix it in both branch and also be the less painful experience 

for writers and translators ? 




Francisco