kicad-doc-devs team mailing list archive

[Marco Ciampa <ciampix@xxxxxxxxxx>]

On Wed, Jul 29, 2020 at 01:51:14PM +0200, Mathias Neumann wrote:
> Hi at all,
> 
> as a new Member in the Documentation Team i have read this discussion and
> want to say my opinion about the Workflow with a stable and a developer
> branch.
> 
> 1) It makes sense to have a developer Branch (master) and an stable.
> 
> My suggestion is that the stable documentation contains the suitable
> Screenshots and the Documentation for the Features which are build in for
> the major Releases like 5.0 or 5.1

ok

> 2) The Developer branch is for the Versions like 5.1.1 5.1.2 .... in this
> branch the Developer of the Functions

I agree but unfortunately devs hardly document any new function at all.
You probably should ask this in the devs ml, not here.
Good luck.

> must contain a lowlevel description
> how the function work and a screenshot which we can take and bring it to the
> stable branch. 
> This makes writing the documentation easier because we still
> have the pictures an must not extra make them.

+1 but as I said above, that is not really up to us...

> 3) Before we can do the two point above we must do a cut and clear the old
> issues and see which are still to do and which not.

> For example the oldest
> issue (https://gitlab.com/kicad/services/kicad-doc/-/issues/154) is four
> years old, so for me as a younger member i don't know what to do with this.

and that in particular is about a CMake issue that depends on devs
(again) since I unfortunately am not a CMake expert at all...

> Can we took an Version for example 5.2 or 5.3 in which we have a tidy up
> Issue list and the documentation has Screenshots which are suitable for the
> Version?

yes we can... ;-)

> The Last Point i want to discuss is, can we make a little Video tutorial
> where a new Person can easily see what to do when he want to begin writting
> the docs.

It's the easily part that I miss here... I may be biased here of course
since I do not particulary like video tutorials. I think IMHO that a well
written text documentation is better. When you have some doubts, written
docs are easy to cut & past to email to ask for a clarification to the
author; how can you do it by video?

I do not want to be totally negative here but ... please explain why a
video should be better than text...

--

Saluton,
Marco Ciampa