As you might know, there is a chapter in the documentation called Getting Started in KiCad which is at this point entirely out of date and does not really cover the modern KiCad workflow. I have seen many people point new users at various video series or posts on the user forum as more accurate and modern introductory tutorials.
Since the release of 6.0 is drawing near, we are trying to figure out what to do with this chapter. Right now, I’m just about the only person working on updating the documentation for 6.0, and I am focused entirely on the “reference manual” portion of the documentation.
I don’t personally believe that the reference manual needs to contain a “getting started” chapter in tutorial form, but I’m happy for it to be there as long as it is up to date and correct. Since it is not looking possible to do that for 6.0, we are currently planning on removing this chapter from the website and published documentation.
So, before we make this call and delete it, I wanted to check: is there anyone who is interested in volunteering to write a new version of this document, covering the very basics of the modern KiCad workflow using the latest nightly builds (pre-6.0)? I’m happy to assist with formatting and gathering images, and we have a volunteer copy editor to make sure the writing will fit in stylistically with the rest of the manual. We just need someone who is up for putting in the time to create an outline and then write the content for it.
If nobody volunteers for this, we will remove this chapter before 6.0 is released. We can always add a “getting started” chapter back again in the future if someone wants to write it later.
If you are interested, please contact me directly. Thanks!
I have already updated parts of it in the past so I’m familiar with the git+tools workflow (although I have to get familiar with it once again…)
First we should come to a consensus about the large picture, what to include and what not to include. Then plan a new skeleton. It should follow the old one as closely as possible but still remove the old workflows and include the new ones. It’s important to help the user to get familiar with things which can’t be seen, especially control keys + mouse.
I don’t think that it needs to follow the skeleton of the old one closely, where that skeleton is no longer useful or not as clear as it could be. I do not want to develop an outline of the document here in this forum thread, but if you are interested in working on this with me let’s chat directly. We also have some new diagrams from @ixhuti that could be used in place of the “monster flowchart”.
Honestly at this point I would be fine if someone wanted to write it and didn’t want to use Git or Asciidoctor at all – even if someone wrote it in google docs I’d be happy to do the translation and commit it.
The problem is that the old skeleton is really not an ideal one for modern KiCad. If the main task here were to just update the screenshots and change a few things here and there, I would do it myself. Really it needs to be started from scratch in my opinion.
I have thought about that, too, if you mean that someone who can write documentation writes it in some format, and someone who knows how to edit with the proper tools takes copies and pastes text written by someone else.
One of the nasty parts is updating all the numbering. IIRC it can’t be done automatically, or can it?
You mean the numbers in the step-by-step tutorial? I’d remove them, personally. But, if you want to keep them, so many of the steps will be different that it is not worth worrying about I think.
Yes and no. For example eeschema needs touching every passage because the editing paradigm has changed. But what needs to be achieved may still be the same and maybe parts of a each passage can be taken from the old one. But I haven’t actually read it closely lately.
I don’t insist, but when I first learned KiCad I used the tutorial and I think it was very clear and helpful with the step-by-step numbering. That’s why I would like to keep it.
I attempted to write a beginner guide a year ago. It quickly becomes evident that the writing is painfully difficult to refer to the names of menu icons and drop down items as text. There need to be lots of small screen grabs which often don’t bring context and are not quickly found on the screen.
It CRYS for a video where people can play along at home. To me, a well done video is much better for a tutorial.
I suggest removing the chapter and focus on writing the doc as the reference.
Reads well, but:
Where do you find someone willing and able?
A well done video requires a script. A script is a Getting Started Guide.
I just read the Getting Started Guide for the first time.
I can see Eelik’s point, in that the existing guide, is some sort of framework for a new edition.
My two bobs’ (cents’) worth:
I’d drop Getting Started and rely on an indexed reference manual and an indexed FAQ.
The reason being, FAQs are a far less daunting proposition than a whole Getting Started, and properly indexed, sequenced and updated, your FAQ will end up a “Getting Started And More”.
I am going to start throwing around a word that I do not really know…wiki.
Would it be possible for forum members to contribute bits and pieces (or maybe edits) according to what they think they know? So I could write something and someone else could edit an improvement. Probably need one or two dev’s to exercise some control over the process so it is not a complete free-for-all. Once a chapter is good it can be frozen.
My idea would be to focus some effort on making the whole thing easily searchable. Attaching keywords or key phrases that the beginner might think of, even if the text is not directly used. My thinking is that this might be more useful than other methods of indexing. When I am looking for info in an IC datasheet, I want an electronic copy that I can search; much better than a printed hard copy.
I think we saw earlier that videos…well some users like them and others not so much. I am in the latter category because I am usually searching for a specific tidbit. But there may be some specific cases where they are useful.
Also can/should we sift through all of the newer FAQ to see what may be close enough to use or tweak?
FAQs and wikis are both great ideas and fit in more to a community-managed thing than an “official” manual. Right now, this forum is the de-facto place where FAQs go. Maybe it would be best to put the energy into maintaining FAQs here rather than starting some new platform for it.
As for the Getting Started guide, it should be more of a simple tutorial to familiarize people with the basics of KiCad (how the UI works, what the terms mean, etc). I have an outline in mind for what I think a good guide would look like that would not conflict with keeping a FAQ on the forum.
There already exists a thread about text vs. video. Let’s discuss here only about the written guide, and there’s no need to suggest dropping it. If nobody writes it, it will be dropped. Otherwise we should rather discuss about how it will be done and what it will be.
When people are getting started, they need something to grasp, or some of them do. An index or a collection of documents isn’t enough for many. Even I, who generally like to get familiar with software by going through menus, toolbars and preference dialogs liked the tutorial very much even though I didn’t complete it. It would have been very difficult to start learning KiCad without it, especially because I didn’t have much previous experience in EDA software or circuit/pcb design. I designed my first, very simple board with two connector symbols/footprints utilizing the tutorial. (It went into production.)
FAQ and a tutorial serve completely different purposes and complement each other. None of them can replace the other. Certainly it’s useful to read through the FAQ when planning the tutorial.
The tutorial must be tight, controlled and consistent. Wiki may be a good way to do it, but only if people really know what they are doing from the standpoint of the whole document. Our FAQ is a random collection of different kinds of texts and topics, widely differing in scope, style and quality.
I think that a moderator or controlling authority (not me) is needed. But I think that restricting the process too much will result in more empty space where the instructions are desired. So long as the result is clear and easy to understand. Like hairdo’s, style is over-rated.
BTW a good way to start might be one place for forum members to post “Instructions I would like to see in the Getting Started Guide.”
EDIT: While some limits are needed, I think about how in college I learned a topic better from professor A than from professor B. Maybe another student did better with professor B. My point is that having two or three different explanations for a given topic might be helpful in some situations. (Keep in mind that KiCad gets used by people who use different workflows; different modus operandi.) I think that (similar to the FAQ) the contributor names could be listed. Most important is that the topics be searchable and indexed reasonably well. Indexing and keywords could be built over time.
I do not see a problem with that so long as the desired information can be found and understood. We are not competing for a Pulitzer prize.
A wiki such as I imagine should be edited for accuracy.
Ultimately there will be some good ones written independently for people that have reasons of their own. I’ve seen sites that simply link to things like that. We could perhaps get a listing of some of those folks and see if they are going to continue.
It would probably be in the interest of the folks doing the paid tutorials that were mentioned here earlier to have a simple one set up as a teaser. I think they had a free level? I don’t really remember now but that would be a stable way forward.
Planning on making some Getting To Blinky for 6.0 soon, but I would not nominate it as an official “Getting Started” guide. I plan to post those to the Contextual Electronics YouTube channel, as I have with v3, 4, 5. I’m happy to discuss doing other videos on the official KiCad channel but I will not be calling them Getting to Blinky.
Agree with @eelik that the FAQ or really any other information on the forum should be used as “official”, either. We already have wikified posts on the forum for people with sufficient seniority. We should be able to move other posts to wiki status on a post-by-post basis, but I think that’s different than a true wiki. It is a significant undertaking to maintain a wiki, as the ones based on MediaWiki (wikipedia.org base software) are rife with spam.
I am truly amazed at all of the wonderful participation on this user forum, but I don’t think we should make moves to consider it anything other than a secondary resource for the community.
I agree with Jon (as usual ). I think for the early days of 6.0, it’d be sufficient to point to outside resources like videos/this forum as a temporary solution and then implement the Getting Started shortly thereafter.
@craftyjon if you’d like help recruiting people outside of this forum to help contribute to the Getting Started guide, I am happy to help amplify the message.
). I think for the early days of 6.0, it’d be sufficient to point to outside resources like videos/this forum as a temporary solution and then implement the Getting Started shortly thereafter.