Page 2 of 3

Re: Thinking of writing a technical FAQ

Posted: Tue Jul 10, 2018 9:54 pm
by mattmiller
Looks like a good start :)

Re: Thinking of writing a technical FAQ

Posted: Wed Jul 11, 2018 8:47 am
by GAP
jamesh wrote:
Tue Jul 10, 2018 3:55 pm
hippy wrote:
Tue Jul 10, 2018 2:22 pm
Not sure if these would all be considered 'tech questions' but are some of the things which seem to come up time after time, in no particular order ...

Which Pi variant should I buy ?
When is the next version of a Pi arriving; wait or buy now ?
Can I use my Pi as a desktop replacement ?
Is this Pi a fake or a clone ?
How do I set a static IP address ?
Why isn't WiFi working / No Interfaces Found / No wlan0 ?
How do I create an AP / hotspot / captive portal ?
My Pi cannot access the internet.
Why has my screen gone black ?
Is the Pi suitable for Industrial use ?
Can I use the Pi in a commercial product ?
How do I add an on/off button or switch ?
Can I just pull the power ?
How can I power my Pi from batteries ?
How do I put a Pi in my vehicle ?
How do I power multiple Pi boards ?
How do I suspend the Pi to achieve minimal power use ?
My SD Card has become corrupted.
My SD Card has become Write Protected.
Why are my edits not there after rebooting ?
How do I create a read-only SD Card setup ?
How to boot from USB / HDD ?
How to use a Pi 3B SD Card on a Pi 3B+ ?
Windows is only showing a few MB on my SD Card.
How do I get Video and Audio input ?
How to run a program / python script at start up ?
Crontab isn't working.
Why does Python script run in IDLE but not as a command ?
Do I need heatsinks ?
How do I connect a fan ?
How do I share my Pi with Windows ?
How do I see Windows from my Pi ?
How do I change the hostname ?
How much current can I draw out the 5V and 3V3 GPIO pins ?
Have I fried my Pi ?
How do I control a relay / read a button ?
How do I run my .exe program ?
Good list, I'll work through and see what I can magic up.
Bit of feedback from a new user.

The ones in bold are questions I have asked since buying my Pi at the beginning of the year.

I know that Pi is supposed to be used for educational purposes but if a user cannot attend a class then FAQs with explanations from a simple point of view would be very helpful.

My 50c worth is since starting my Pi journey I have found that the people who have the knowledge find it difficult to impart that knowledge in layman's terms, this is something I struggled with when I was assigned apprentices in my workplace.
It is hard to do that.
FAQs may go some way to solving that.
The people who write them may have to approach the issue from an educational point of view rather than "do this it will work" which teaches nothing.
Just my opinion please feel free to disregard it.

Re: Thinking of writing a technical FAQ

Posted: Wed Jul 11, 2018 9:42 am
by jamesh
Useful to have some instant feedback on specifics - I'll update what I have done so far. Thanks.

Re: Thinking of writing a technical FAQ

Posted: Wed Jul 11, 2018 1:52 pm
by hippy
Looking good so far. I like the short and sweet approach with links to additional information. That makes it very readable and people will more likely read the lot even if some things are not of particular interest to them. It's all good information to know as well as being a FAQ.

My list was just a random jumble covering general issues, setup, usage, software and hardware. It might be worth grouping related things into relevant sections.

Re: Thinking of writing a technical FAQ

Posted: Wed Jul 11, 2018 7:45 pm
by hippy
Another one for the FAQ -

How many USB devices / hubs can I attach and use with a Pi ?

Re: Thinking of writing a technical FAQ

Posted: Wed Jul 11, 2018 9:43 pm
by jbudd
Another faq, might already have been mentioned: Why can't my PC read the files on the Linux position?

Is the SD card hot swappable if the pi is booted from usb?

When is NOOBS the wrong way to set up my Pi?

And possibly more tutorials than FAQs:
How can I change the pi's behaviour through cmdline.txt/config.txt?

How can I access the Linux partition with a live CD boot or a usb reader?

There are a lot of tutorials in the forum that are made less useful by having lots of responses, some improving on the first post, some not. It would be nice to see a forum section for the most valuable tutorials but with discussion confined to a separate thread. They would need to be kept up to date too.

Re: Thinking of writing a technical FAQ

Posted: Wed Jul 11, 2018 10:39 pm
by jerrm
jamesh wrote:
Tue Jul 10, 2018 8:47 pm
I'd already done some of the suggestions above, so perhaps best if I link to the work in progress so you can see where I am at. Not copy edited yet.

https://github.com/raspberrypi/document ... cal-faq.md
The CPU utilization issue for net/usb booted Pis should be documented somewhere. Probably better not in the faq, but in the actual docs.

Re: Thinking of writing a technical FAQ

Posted: Thu Jul 12, 2018 12:19 am
by hippy
Another -

Can I combine two Pi to make a better / faster Pi ?

Re: Thinking of writing a technical FAQ

Posted: Thu Jul 12, 2018 1:30 am
by bertlea
I think it will be more effective to save volunteers’ time on FAQ questions/answers if the forum has a chat-bot automatically answer posts based on the FAQ document. Of course, this is only for posts that the chat-bot determined it can be fully answered by the FAQ document. Even better, if the bot can automatically move such FAQ posts to a separate section so it will tidy-up the forum too. :mrgreen:

Re: Thinking of writing a technical FAQ

Posted: Thu Jul 12, 2018 3:20 am
by ejolson
bertlea wrote:
Thu Jul 12, 2018 1:30 am
I think it will be more effective to save volunteers’ time on FAQ questions/answers if the forum has a chat-bot automatically answer posts based on the FAQ document.
Are you volunteering to create and maintain the chat bot?

Maybe the FAQ could have an entry on how to edit files on the root partition using a Mac or Windows PC and how to reset lost passwords.

Re: Thinking of writing a technical FAQ

Posted: Thu Jul 12, 2018 5:33 am
by bertlea
I wish I had that level of knowledge and skills on Natural Language Processing! I tried NLP last year and confirmed it is beyond my abilities. :(

Re: Thinking of writing a technical FAQ

Posted: Thu Jul 12, 2018 9:30 am
by jamesh
bertlea wrote:
Thu Jul 12, 2018 5:33 am
I wish I had that level of knowledge and skills on Natural Language Processing! I tried NLP last year and confirmed it is beyond my abilities. :(
No-one at Pi Towers has any NLP experience, so I suspect there will be limited options in that area!

Re: Thinking of writing a technical FAQ

Posted: Thu Jul 12, 2018 9:30 am
by jamesh
hippy wrote:
Thu Jul 12, 2018 12:19 am
Another -

Can I combine two Pi to make a better / faster Pi ?
Already done that after it came up again on the forum....!

Re: Thinking of writing a technical FAQ

Posted: Thu Jul 12, 2018 9:40 am
by bensimmo
Do you mind us normal people editting with pr's, or do you want it leaving for the checking team? (Spelling, typo etc)


Just a quick one.
The samba part, you could point to some of "your" MagPi articles.
https://www.raspberrypi.org/magpi/samba-file-server/

Re: Thinking of writing a technical FAQ

Posted: Thu Jul 12, 2018 9:46 am
by jamesh
bensimmo wrote:
Thu Jul 12, 2018 9:40 am
Do you mind us normal people editting with pr's, or do you want it leaving for the checking team? (Spelling, typo etc)


Just a quick one.
The samba part, you could point to some of "your" MagPi articles.
https://www.raspberrypi.org/magpi/samba-file-server/
I think I would prefer comments here. Once it's online, then people can push in their own PR's that can then be assessed but at the moment I'm curating it from these comments.

I'll add that Samba link for the moment, I suspect I need to add something to the official docs on Samba anyway.

Re: Thinking of writing a technical FAQ

Posted: Thu Jul 12, 2018 10:04 am
by DirkS
Will the Tech FAQ get an index as in https://www.raspberrypi.org/help/faqs/ ?
It's not easy to get a link to an item without it.

Re: Thinking of writing a technical FAQ

Posted: Thu Jul 12, 2018 10:09 am
by bensimmo
DirkS wrote:
Thu Jul 12, 2018 10:04 am
Will the Tech FAQ get an index as in https://www.raspberrypi.org/help/faqs/ ?
It's not easy to get a link to an item without it.
I think there is a problem with the way GitHub works and how making it into a webpage with links works, meaning the index will currently be dropped.

Re: Thinking of writing a technical FAQ

Posted: Thu Jul 12, 2018 10:12 am
by DirkS
bensimmo wrote:
Thu Jul 12, 2018 10:09 am
DirkS wrote:
Thu Jul 12, 2018 10:04 am
Will the Tech FAQ get an index as in https://www.raspberrypi.org/help/faqs/ ?
It's not easy to get a link to an item without it.
I think there is a problem with the way GitHub works and how making it into a webpage with links works, meaning the index will currently be dropped.
Somehow RPF have it working for the 'regular' faq though. See https://github.com/raspberrypi/document ... aster/faqs and https://www.raspberrypi.org/help/faqs/
No idea how they did that, but apparently they somehow get generated...

Re: Thinking of writing a technical FAQ

Posted: Thu Jul 12, 2018 10:16 am
by DirkS
@James
Not sure if it has been mentioned already, but there may be some potential faq bits in the pitfalls sticky: viewtopic.php?f=91&t=83372

Re: Thinking of writing a technical FAQ

Posted: Thu Jul 12, 2018 10:28 am
by piglet
jamesh wrote:
Tue Jul 10, 2018 2:07 pm
piglet wrote:
Tue Jul 10, 2018 1:28 pm
Which FAQ area are you thinking about adding to?
A new technical faq at the root of the docs tree.
I'm sure this must be very familiar to you - but I've never seen this before. It's not easily found by any new person likely to need to know the information. I can't see any mention of "github" on the https://www.raspberrypi.org main page.

If you're wanting people to find it it's going to need significantly better linkage from the homepage.

https://github.com/raspberrypi/documentation/

Re: Thinking of writing a technical FAQ

Posted: Thu Jul 12, 2018 10:33 am
by bensimmo
DirkS wrote:
Thu Jul 12, 2018 10:12 am
bensimmo wrote:
Thu Jul 12, 2018 10:09 am
DirkS wrote:
Thu Jul 12, 2018 10:04 am
Will the Tech FAQ get an index as in https://www.raspberrypi.org/help/faqs/ ?
It's not easy to get a link to an item without it.
I think there is a problem with the way GitHub works and how making it into a webpage with links works, meaning the index will currently be dropped.
Somehow RPF have it working for the 'regular' faq though. See https://github.com/raspberrypi/document ... aster/faqs and https://www.raspberrypi.org/help/faqs/
No idea how they did that, but apparently they somehow get generated...
I think that's still the old WP FAQ's
Ben/James manually create the headers only now (so no sub-section linking)
They may find a way around it, to automate it hopefully.
https://github.com/raspberrypi/document ... -404208821

Re: Thinking of writing a technical FAQ

Posted: Thu Jul 12, 2018 10:35 am
by bensimmo
piglet wrote:
Thu Jul 12, 2018 10:28 am
jamesh wrote:
Tue Jul 10, 2018 2:07 pm
piglet wrote:
Tue Jul 10, 2018 1:28 pm
Which FAQ area are you thinking about adding to?
A new technical faq at the root of the docs tree.
I'm sure this must be very familiar to you - but I've never seen this before. It's not easily found by any new person likely to need to know the information. I can't see any mention of "github" on the https://www.raspberrypi.org main page.

If you're wanting people to find it it's going to need significantly better linkage from the homepage.

https://github.com/raspberrypi/documentation/
It's Work In Progress so not pushed to the main site yet, I think they are trying to move all the old WordPress site pages over to GitHub as they go along. (and have time) and then push them back.
James will confirm either way I guess.

As a side: If you click on the big HELP button at the top of the page and then Documentation... you'll see it's all github, but you don't need to know that.
or right down in little text at the bottom.
Of course, this is much easier when not on a mobile device. (I say that, as on mobile you need to know what the three bars mean in the top right hand side)

Re: Thinking of writing a technical FAQ

Posted: Thu Jul 12, 2018 10:44 am
by jamesh
bensimmo wrote:
Thu Jul 12, 2018 10:35 am
piglet wrote:
Thu Jul 12, 2018 10:28 am
jamesh wrote:
Tue Jul 10, 2018 2:07 pm


A new technical faq at the root of the docs tree.
I'm sure this must be very familiar to you - but I've never seen this before. It's not easily found by any new person likely to need to know the information. I can't see any mention of "github" on the https://www.raspberrypi.org main page.

If you're wanting people to find it it's going to need significantly better linkage from the homepage.

https://github.com/raspberrypi/documentation/
It's Work In Progress so not pushed to the main site yet, I think they are trying to move all the old WordPress site pages over to GitHub as they go along. (and have time) and then push them back.
James will confirm either way I guess.
I am trying to move all *documentation* in to github. Obviously the rest of the site will remain with Wordpress, but technical stuff, moved to github, will be much easier to edit and control, and gives the ability for third parties to send in PR's, which is obviousy not possible with wordpress.

As above, the tech faq is a work in progress, and has not been linked in yet.

How it works: All edits are done to the github repo as markdown. Every hour or so this is automatically translated to HTML pages and published under www.raspberrypi.org/documentation/. The top page is still static however, and that is where the main tech FAQ link needs to be. There is a problem with anchors links though, which is why the index on the existing FAQ (which we are moving to github) is proving a PITA. Currently, I am planning just to have links to subsectinos rather than individual quesitons, otherwise is a LOAD of typing in manual anchors. TBH, I'm not a fan of the index anyway - you have to scroll a couple of pages to get to a particular question, and if you are having to do that why not just scroll down directly to the question.

Re: Thinking of writing a technical FAQ

Posted: Thu Jul 12, 2018 11:06 am
by DirkS
jamesh wrote:
Thu Jul 12, 2018 10:44 am
TBH, I'm not a fan of the index anyway - you have to scroll a couple of pages to get to a particular question, and if you are having to do that why not just scroll down directly to the question.
Problem is that it's virtually impossible to figure out the link to an item in the FAQ (which would be very useful in forum posts)
On Github (and Wikipedia for example) you can easily get a permanent link to a section (header / item).
That doesn't work on the documentation pages, though...

Re: Thinking of writing a technical FAQ

Posted: Thu Jul 12, 2018 11:14 am
by hippy
jamesh wrote:
Thu Jul 12, 2018 10:44 am
How it works: All edits are done to the github repo as markdown. Every hour or so this is automatically translated to HTML pages and published under www.raspberrypi.org/documentation/.
I have no problem with that, it is how most content management systems handle things; raw content in a simple to edit format, formatting and decoration seen by the reader created by an automatic publishing generator.

I would have thought it possible to have the published content generator determine the sections, their title, add anchors during generation, and create an index of those alongside that. It could add the index into the generated page or keep it in a separate index page.

It should be just a few lines of code to achieve that and the content creator doesn't have to worry about indexing themselves, keeping indexes up to date.