kicad-developers team mailing list archive

[Brian Sidebotham <brian.sidebotham@xxxxxxxxx>]

On 22 September 2011 15:02, jp.charras <jp.charras@xxxxxxxxxx> wrote:
> Le 22/09/2011 14:55, Wayne Stambaugh a écrit :
>>
>> On 9/22/2011 6:04 AM, fabrizio wrote:
>>>
>>> Hello,
>>> Now that the new 26pth kicad icons are basically finished (I'll maybe
>>> send reviews of some of them if necessary) I'd like to bring up the
>>> topic of documentation.
>>>
>>> As far as I understand Kicad has some manuals written in OpenOffice
>>> and a one step by step tutorial. On top of that there are the
>>> translations of them, all done in OpenOffice.
>>>
>>> Before the new face-lifted kicad gets released, these manuals need to
>>> be updated and maybe reviewed. this might suggest that we could choose
>>> a different documentation format for kicad (web-based, online
>>> wiki-based, html documentation accessible via the kicad menu,
>>> restructured text, etc.).
>>
>> How do we get the documents from the wiki into PDF (the format supported
>> by
>> Kicad) for the binary distributions that most users will install?  The
>> user
>> manuals are currently kept in a separate repo so that documentation
>> contributors do not need access to the source repo and that some level of
>> change control is maintained.  This prevents anybody from dumping anything
>> into
>> the documentation and allows for changes to easily be rolled back.  I have
>> no
>> preference over the format used for generating the documentation.  There
>> are
>> plenty of good alternatives available.  I personally will continue to
>> generate
>> the file format documentation in ODF format.  If someone wants to
>> translate it
>> into some other format, I'm OK with that.
>>
>
>
> I also will continue to generate the file format documentation in ODF
> format.
> For me the pdf files are like binaries for a program,
> and the odf files are the sources (like the .cpp files).
> From .odf files other formats (pdf, html ...) are easy to generate.
>
>
>>>
>>> What are the options out there? What do you think we should do about
>>> it? Who would be interested in working on it?
>>>
>>> Just as term of comparison, here:
>>> http://inkscape.org/doc/index.php
>>> http://tavmjong.free.fr/INKSCAPE/MANUAL/html/index.php
>>> you can find the only (on-line) documentation available of probably
>>> one of the best open-source graphical tool.
>>>
>>> in case of inkscape, documentation is online and tutorials are in the
>>> inkscape native format.
>>
>> I'm not a big fan of on-line only documentation.  There are times when
>> there is
>> no internet connection available and you need access to the documentation.
>>
>> Wayne
>>
>>>
>>> Regards
>>> Fabrizio
>
>
> --
> Jean-Pierre CHARRAS
> KiCad Developers team.
> KiCad Developers <kicad-developers@xxxxxxxxxxxxxxxxxxx>

I have always found the KiCad supplied documentation to be very
thorough and useful - the few times I've needed to resort to it. I
picked KiCad up very quickly as it seemed intuitive to me, but maybe
it's because I've been doing PCB design for 15 years or so with
various packages. KiCad has been a revolution in my books. gEDA has
always been very alien to me and not user friendly to use. I've used
KiCad exclusively for around 4 years now.

The documentation is certainly not lacking.

With regards to the source format, ODF is probably the easiest and
most productive to use for the author, especially as there only seem
to be a few people doing documentation anyway. I have in the past
investigated using tex for version controlled documentation, but it is
absolutely horrible to use. Its main bonus is being able to represent
formulae, but even then there is a lot to learn for the syntax to do
that too.

Best Regards,

One happy customer. :-)