kicad-doc-devs team mailing list archive

[Nick Østergaard <oe.nick@xxxxxxxxx>]

Hi Francisco

Thank you for your interest and effort. I have added you now, you
should be able to manage the issuetracker, please test it.

Some thoughts about yours:

Tracking things to be updated or changed is better done in the issue tracker.

I think all effort should be focused on the master branch for now.
Technically it is very difficult to cherry pick things on the docs
over time due to the nature of it and reformatting. I think it is
better to just copy sections from master if deemed compatible with 5.1
whenever needed, but certainly focus on making master better first.
Then later it is easier to take chunks from master and adapt them to
5.1.

I would like more people to be able to review merge requested, but
please make pullrequests with atomic commits as reasonably possible.
It makes it easier to review.

Nick

On Thu, 14 May 2020 at 14:34, <f.dos.santos@xxxxxxx> wrote:
>
> 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
> --
> Mailing list: https://launchpad.net/~kicad-doc-devs
> Post to     : kicad-doc-devs@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~kicad-doc-devs
> More help   : https://help.launchpad.net/ListHelp