Will "Getting Started" tutorial be updated?

@mollux. I agree with the points made by @dchisholm. A noob can be helpfull if he so dciedes to help.

Ok, @dchisholm and @Joan_Sparky… The documentation source is written in asciidoc and is hosted at https://github.com/KiCad/kicad-doc. In github terminology a pull-request is a way to send improvements of text files (source code or written text, mostly) to the “Principal Author(s)” as you call them.

Read more about contributing to the docs at https://github.com/KiCad/kicad-doc/blob/master/README.adoc.

A guide on performing a pull request can be found at https://help.github.com/articles/using-pull-requests/.

@nickoe I am not sure how far a noob can rewrite documents which usually require a depth of knowledge and experience using new features. Usually the best person to write the document if the person who designed and coded that part of the software. This is usually how companies function. But this being an opensource project, documentation is always a task for someone really willing or has a drive by himself to keep it updated or software is maintained by a company who relies on documentation for their work. But really documentation in many opensource projects is not good. I might be wrong about a noob not being able to help, but the effort for a noob is much much higher as he still has to acclimatize, find and learn before he can write anything.

This might be naive in many ways, but can we get a small community fund for 2 tasks, one is to get the documents updated and other is for getting a developer resource to fix the library gripes. I think these two changes will make a huge difference for newbie’s like me and over all community would grow.

The First one is comparatively easy compared to the next one which involves a lot of developer interaction and approval.

I believe hiring/paying community members on completion of certain amount of tasks could be an incentive for some to finish the work. I know this is not how opensource works usually, but then things need to be done, and someone has to do them.

Using something similar to https://www.bountysource.com/ , achieve a common goal might be good way to go.

@MrAdi I disagree with you on the first point. A noob can be a valuable contributor if he really want to be one.

On your second point, it is indeed naive, people are writing the docs, and people are devloping. The community is already growing.

Hiring and paying people to do stuff is one way to do something, but this will require people to pay. Will you fund me to be able to work full time on KiCad? I don’t think so, but that would be one way to get stuff done quicker.

Anyway, I fell this meta-discussion will not add any value to anything anyway. I regret I ever started to reply to you, in the hope that you would actually contribute. But here it is.

1 Like

Can I suggest removing the Getting Started tutorial until it can be rewritten and to point to other sources instead? I already gave up trying KiCad once due to a total inability to get anywhere with the tutorial because of all the inaccuracies.

On this occasion (six months later and after reading there was a new version available) I decided to power through and six hours later I finished it after much online searching, reading the main documentation and generally poking it with a stick and seeing what happened. I probably learnt a lot more in the process than I otherwise would have done, but that is not the point of a “Hello World” tutorial.

I don’t want to come across as negative as I think the program itself is an amazing achievement, but the Eeschema section of the tutorial lets it down badly (the rest is fine). Making the introduction so painful is not the way to encourage new users, so pointing to other tutorials instead, such as Udemy or Conceptual’s youtube vids, would be better until a rewrite can be arranged.

Hi Bob! Just started remaking the videos, not sure about the actual tutorial itself. Two videos in the bag.

I’ll ask the developers if the new version of the video tutorials can be linked (or embedded) on the main kicad.org page. At the very least, I think the tutorial and getting started materials should be tagged with which version they are referring to.

I support that :smile:

I thought that is how open source works - don’t think you get everything covered by a lonely tutorial.
When I code Google always drops me off at Stackoverflow these days… even KiCAD is covered on one of their ECAD subsections for some questions I have/had.

@BobS what exactly are the inaccuracies?

Generally it looks ok to me, but I didn’t go through every step, and I’m no longer a newbie so don’t have that perspective. The eeschema tutorial is a walk through of a lot of features, probably not all are needed for a first look. It might benefit to have a really simple example, followed by a more advanced example.

If you have suggestions, then raise them on https://github.com/KiCad/kicad-doc/issues, but you will need to be more specific than “needs a rewrite”…

I raised some issues in the 1st post here -

…Right-click menus are different in the manual, there is no “PIC12C508A” microcontroller to be found (needed for the practical example), do I press “A” key or “Shift-A” to add a component? (manual is ambiguous), if 25mils is the recommended grid size why default is 50mils, “Help” files don’t link to the pdfs that exist in the install folder… etc

That’s just from the 1st few pages of the guide heh. There’s workarounds, of course. The PIC12C508A can be found on github, for instance. Perseverence! Of course, you want to encourage noobs (like me), not turn them away to something (immensely intuitive) like Diptrace.

Chris Gammell, we eagerly await your new set of video tutorials! :slight_smile: Thank you!

Thanks Chris - that is excellent news - although I found the originals very helpful too.

Let me say again that I think the software is excellent as far as I have used it and the extra faffing about was probably a good learning experience in the long term - but if the first steps are difficult, many will just walk away (as I did once already).

I fully realise that finding people to write, check and double-check documentation is difficult - especially for multiple OS platforms. Everyone is busy earning a crust or seriously studying. That is why my main point was the suggestion to provide links to existing alternatives until someone(s) can be found to do the rewrite.

Cheers, Bob.

https://contextualelectronics.com/learning/getting-to-blinky-4-0-part-1-2-3/

Chris, allow me to be the first to say (on behalf of everybody here) a mighty “THANK YOU”.

Legend! :thumbsup:

Have you checked recently?

Looks the same to me… again, please be specific.

If you follow the instructions, it worked for me…

I don’t think that is ambiguous, in all guides I have ever seen “a” means press the “a” key, and not Shift-A or Ctrl-A or Alt-A. A couple of seconds would verify which is meant. But if you think there is a problem, please suggest some wording to make it less ambiguous…

The current text recommends 50 mils, but anyway that is a question about the program design.

Seesm to work with my 4.0.0 install, again, please be specific. Which files?

These seem like minor issues, rather than anything needing a rewrite. Is the problem that nowadays people prefer video guides rather than reading through text?

Anyway, if you want to help improve kicad, raise specific issues on https://github.com/KiCad/kicad-doc/issues. Generalised complaints here are unlikely to get acted on.

Yes seems to have fixed some things in the Getting started manual, that’s great!

With the “A” and “Shift+A”… If you type “?” to get up the list of shortcuts, it says “Add Component = A”. But if you go menu/Place/Component, it lists the shortcut as “Shift+A”. They both work, sort of similarly.

Grid-size, yes I mixed it up. Default is 25mils, but manual says “it is recommendable to use a grid of 50mils for schematic”. Why then is the default 25mils?

But these are tiny issues. Seems like someone’s addressed some of the other ones, which is good. Obviously not so minor as to not needing addressing? Reading text guides is great if it flows logically. You shouldn’t have to second-guess things or puzzle needlessly over ambiguities.

Yes, I’ve noticed there is some inconsistent behaviour here. In fact if you do Shift-A as the menu says, it doesn’t work! However, if I have Caps Lock on, the A key still works, and Shift-A still doesn’t. I will raise a bug on Kicad about that. But this is a bug in Kicad, the tutorial is correct. Even so, I am trying to get the text replaced with icons, unfortunately getting improvements is an uphill struggle :frowning: https://github.com/KiCad/kicad-doc/issues/226

Form what I can see and remember, the default size is 50 mil. Either way, the tutorial is correct.

[quote]Reading text guides is great if it flows logically. You shouldn’t have to second-guess things or puzzle needlessly over ambiguities.
[/quote]

I absolutely agree with that. But I think it is inevitable that any single guide will have ambiguities, condensing complex concepts into a few easy to digest sentences always suffers from information loss. It’s always a good idea to consult a few different sources.

It’s also why forums like this are useful, people can ask “I’m doing step 14 and it says do xx. Can anyone explain?”. If a lot of people ask the same question, then improvements can be identified.

I will withdraw my previous suggestion to raise issues on github; don’t bother. The team there don’t seem to want to change anything, even where they admit things are wrong!

I will create a fork anyway to submit pull requests.

Apparently “not a bug”, it’s the way Kicad is designed. Shift+A enters “Place component mode”, but does not start the place component dialog - it is equivalent to clicking the tool bar button. To actually place a component, you have to click in the drawing area or press the A hot key.

Oh well, we’ll have to forget about trying to improve the Kicad user interface. Project lead Wayne Stambaugh is firmly opposed to improving the interface:

I will not change the behavior of hot keys because some users are confused by their behavior.

Wayne didn’t bother to read what I had written, and got the wrong idea, so I think it would be pointless to argue with him!

I’m a new user trying to get through the tutorial. Here are the issues I see so far

Document I’m using (for section numbers referenced below)
http://docs.kicad.org/en/getting_started_in_kicad.pdf

Kicad version and OS in use

kicad-product-4.0.1-x86_64.exe on Win7 Pro:

Section 3.1

  1. When I hover on the component and press r instead of rotation I get a dialog box
clarify selection
       field value
       component R R?

easy enough, it wants component R R? selected then r rotates. however a warning
this will occur would be good, a way to avoid it would be even better!

10 right clicking on R also gets the Clarify selection box, same solution as above

11 History in the PDF is wrong. Since we haven’t yet selected a Barrel Jack, it is not
in history (minor nit, but potentially confusing to a newby and easily fixed!)

19 PIC12C508A-I/SN isn’t in the list of microchip processors loaded by default.
Someone noted this above, along with the suggestion that it is in the repository.
This is correct, and I’ve downloaded the zip from


But I can’t figure out even from reading the manual how to get the symbol from
the zip file into the symbol library. If someone would enlighten me that would be
great, and it should be documented in the PDF as well since it is impossible
to complete the tutorial til you figure out how to do this and it isn’t obvious (at
least to me) how to do it. Since I’m stopped here that is as many issues as I
have for now (perhaps to all of your relief).

Well, I suppose everyone would be satisfied if a user could reassign all shortcuts (which doesn’t seem to be the case at the moment).

Hi vanepp.

You probably already have the library on your library directory, it just has not been loaded into the project by default.

The latest version of the tutorial includes details of how to load the required library.

Before add-component, add microchip_pic12mcu to your Component library files
by Preferences → Component Libraries and press Add button.

It is always worth checking the latest documentation via the link on eeschema’s Help menu (these links appear to be one of the things fixed in 4.01 as they did not work for me in 4.0 ;-)) .
.

More generally, can I just take a moment to thank the person(s) who updated the tutorial :smile: . I know it seems like a small thing to experienced users, but I am certain that making the first baby-steps easier for noobs will pay dividends in encouraging wider adoption of KiCad.

Cheers, Bob.

1 Like
 By using ls -lR from cygwin I did indeed discover that I have the libraries in program 

files. I also saw and tried

Before add-component, add microchip_pic12mcu to your Component library
files by Preferences → Component Libraries and press Add button.

I read that in the tutorial but that didn’t work any better. However when I tried again just now I found my error: I was pressing add in the User defined search path, not component library files (which is above that on the screen), since there are two add buttons it may be worthwhile specifying in the tutorial that you want to press the top add button to add the library not the bottom one. I’d say it was just me being stupid, except that someone else further up in this thread said the same thing (although it is possible that he was referring to an older copy of the tutorial too).
I too would like to thank the folks that create and maintain the tutorial as it is important to have a clear way for a newcomer to figure out how the tool works and I must admit that I was beginning to think that if I couldn’t get the tutorial to work then Kicad may not be an answer for me. Thanks for the pointer as that is what got me to look at this yet again and finally figure out what I was doing wrong.

It may be worth noting in the tutorial that if you screw up (as I have multiple times) and try to restart by deleting the tutorial1 directory you created that you also (at least on Windows) need to delete \Users\Owner\AppData\Roaming\kicad (at least in my case, your path will be different) because it is storing things in there too and will remember them when you recreate your directory.
Now a bunch more issues as I have moved along in the tutorial listed by section number. If this isn’t an appropriate place for this I assume that someone will tell me :smile: . Again indexed by the reference numbers in the tutorial:

6-1
7 click on the first corner, do not hold button down while moving to the other corner as that does something different than create the rectangle.

43 Annotate schematic icon is in the tools menu on the top menu bar (I was trying to find it on the screen …)

45 change “Perform Electric Rules check” to tools -> Electrical Rules Checker.
change Click “Test ERC button” to “Run” in both places.
on Windows clicking “create ERC file report” run save file tutorial1.erc results in “No default editor found you must choose it” . I chose c:\windows\notepad.exe and that seems to work. I expect this will be different for Unix (if the $editor environment variable is set it may not come up on Unix) …

46 Change “Click on the Netlist generation icon” to “Click on tools -> Generate Netlist File”
“Click on Netlist then” to “Pcbnew (default) press Generate then save”

47 change " click on the Run Cvpcb icon " to “click on tools -> Assign component footprint”

49 Add "click til you get “filtered by library” only in the bottom right window then click on the specified library in the left window (i.e. Housings for the IC1 footprint). then double click on the appropriate foot print in the right side window.

52 “File -> save as” to “File -> Save edits”

53 change “File ? Save Whole Schematic Project” to “File ? Save Schematic Project”

54/55 While they do no harm, there doesn’t appear to be any point to them either. Netlist doesn’t appear any where in the project manager and we are going back to Eeschema for the next step so why close it and go to project manager. Perhaps move the comment in 55 about the netlist being an editable text file back to step 52 and eliminate 54 and 55?

56 BOM is now in tools -> Generate Bill of Materials not on the tool bar as stated
The add plugins window opens in Kicad\bin to get to the .xls files you need to click on “scripting”
then “plugins” (neither of which is likely obvious to a newbie). As noted the plugins are in KiCad\bin\scripting\plugins\ not /usr/lib/kicad/plugins/ as stated and the file is thus:

xsltproc -o “%O” “C:\Program Files\KiCad\bin\scripting\plugins\bom2csv.xsl” “%I”

not xsltproc -o “%O.csv” “/home//kicad/eeschema/plugins/bom2csv.xsl” “%I”

3.2 Bus connections.

  We currently have the tutorial1 schematic open from the BOM step in 56 above. There is no 4 pin connector  present. I suspect this example was taken from somewhere else and it needs a schematic (probably other than tutorial1!) created to provide the necessary connectors to connect to the bus or to be only a example for information only (which should then be stated so as to not have changes made to the tutorial one schematic that will trip the user up later).

4.1
5
C:\Users\Owner\Documents\kicad\tutorial1\tutorial1.net shows in the file window, clicking the Browse button opens C:\Program Files\KiCad\bin\scripting\plugins rather than C:\Users\Owner\Documents\kicad\tutorial1\ which in turn has no .net files in it (presumably because the plugins directory was my last reference).
I don’t see how to fix this, but it is likely confusing to a newbie. Obviously they would need to navigate to the correct directory (or just use the one offered in the window, which perhaps is new functionality).

“Click on Read Current netlist then click close” is misleading. It needs to indicate to check the messages window for errors first, because In my case I had screwed up (because going back and verifying the footprints were added fixed it, even though I made no changes) and the message window looked like this (note as it is a unix \n only delimited file, notepad won’t read it properly and I had to use vi in cygwin, it may be an idea to suggest this for windows users in the tutorial as well):

Info: Reading netlist file “C:\Users\Owner\Documents\kicad\tutorial1\tutorial1.net”.
Info: Using references to match components and footprints.
Error: No footprint defined for component ‘R2’.
Error: No footprint defined for component ‘R1’.
Error: No footprint defined for component ‘IC1’.
Error: No footprint defined for component ‘D1’.
Error: No footprint defined for component ‘J1’

which would not have worked at the next step.

6 looks like all components are moved to the center of the screen by default now so this isn’t needed

8 Looks like “hide board ratsnest” button has become “display local ratsnest”

9 Initially I got my friend “clarify selection” when trying to move with “g” but moving out of the window (to notepad where I am documenting this) and then clicking on the tool bar to select the window again, I can now use “g” to move components without the clarify selection window coming up. Confusing to say the least! Documenting how to turn “clarify selection” on and off would be useful (probably early in the tutorial) since I don’t know what I’m doing to invoce it.

11 “Select edge cuts” needs to add “(beteen perform design rules check and show active layer selections)” (preferably with their respective icons) on the tool bar. It was not obvious to me for quite some time what drop down menu you were referring to until I looked at the next screen shot, as a blank rectangle doesn’t appear to be a drop down menu, although in this case it is. As well a screen shot of the finished outline would be useful to know if I had done it correctly. Reminding the user that a double click will terminate the line wouldn’t be a bad bet either.

16 This doesn’t work as stated. An error box saying “Extra Track1 size 0.0100 < min track size” comes up, I assume because the sizes are in mm. I note there is a (inches) at the end of the line. I assume this means the table is intended to be in inches not mm. However there is nothing to tell the newbie how to change from mm to inches here so either that needs to be added (clicking on “in” in the left tool bar did it for me for instance) or the table changed to mm.

19 when the first track is added the rats nest disappears and clicking “display local ratsnest” doesn’t bring it back. In this case with a drawing to refer to that isn’t a problem, and starting a wire on a pin brings up the rats nest for that pin, but it makes it difficult to see when you have connected all the pins.

22 Doesn’t appear to work. With B Cu layer selected, click on Add zones and click on one corner of the board edge rectangle. No dialog box occurs and nothing appears to happen. Moving to the next edge and clicking also causes no change.
This one has me currently stopped until some good person here tells me what I’m doing wrong, because I don’t know how to get the ground plane to place.