← Back to team overview

kicad-developers team mailing list archive

Re: Update of KiCad documentation?

 

I think starting small would be best in this case. The least needed would be a "News" File, that is always refering to kicad stable.

I propose the same way that patches with policy errors are rejected, patches that introduces new functionality or change of existing functionality are required to add to the News file, max one line. Just something like this, I would like markdown formatting.


Changes from Kicad 4
=

NEW: Pcbnew now supports clipboard copy/paste
CHANGE: Delete button now removes entire trace, not just a segment
CHANGE: Icons in toolbar are improved
REMOVED: Autorouter no longer exists


This style could also be applied in the git commit message, making it easy to compile by something such as 'git log | grep "NEW:"'

But since that is lacking, I think starting a new file is best.


On 11/03/2017 09:50 AM, Marco Ciampa wrote:
On Fri, Nov 03, 2017 at 08:55:54AM +0100, Carsten Schoenert wrote:
Hello Wayne,

Am 03.11.2017 um 00:58 schrieb Wayne Stambaugh:
No one is going to argue that our documentation could be improved.  I'm
not really sure what the best approach would be to do that.  I would
prefer that we work with the tools and infrastructure we already have in
place rather than create a new dependency if at all possible.

nobody want's to introduce new tools or dependencies as long as there is
no body that will do the work. And I agree with you, I see no need for
something like that. The existing structure and tool-sets is working
well so far.

  What
about creating a documentation todo list asciidoc file in the
documentation repo.  The list would be broken down into two sections,
undocumented features and out of date/obsolete features.  Each section
can be broken down by application.  This would give folks looking to
help an idea of what needs to be done.

Yes and no, for existing topics that are poorly documented or need some
refreshing due passed time with upstream changes this may work. And
there are some kind of list already due some issues that are raised in
the issue tracker on the repo site.

agree 100%

But my starting posting was more about the currently new but completely
undocumented features that come with version 5 of KiCad. I can't see any
possible effort on that based on your proposal due "external" people
mostly doesn't know what to document at all. At least within the last
year there is no one single addition in progress here.

agree 100% see my previous post

But the main English documentation needs to be ready before any
translators should start.

In an ideal world yes.

1) or at least if someone fixies some spelling errors in the English
language, he/she must also/is responsible to un-fuzzy the corrispondant
strings in all the other languages .po files

and

2) must do this after asking all translators to do commit their
translations to avoid nasty conflicts and race conditions. Merge works
only using some special filters that do not diff comments in translation
files (.po) for example...

The problem here is that to avoid loss of locally updated translations
during a merge, each translator should use a specific merge tool for .po
files. Perhaps this can be resolved with some scripting inserted in the
cmake files. Some operation like this:

make manualname_languagecode_update #contains a git pull ...
mkdir build; cd build; cmake ..; etc... #for check
git commit -a -m "Updated translation of MANUALNAME in LANGUAGE"


I can remember some discussion there I wanted
to change some spelling and formatting of the files in the master branch
(not the 4.0 branch!) which wasn't accepted due the impact in every PO
file down in the various languages. So I don't really want to put again
some energy on that before things are clear.

Right see previous comment...

We need some agreement first what needs or should be added to the
documentation of KiCad5. If there is something like that existing we
than need people who take care on that.

Agree again...


--
 -Kristoffer


Follow ups

References