mattmiller
Posts: 2112
Joined: Thu Feb 05, 2015 11:25 pm

Re: Thinking of writing a technical FAQ

Tue Jul 10, 2018 9:54 pm

Looks like a good start :)

GAP
Posts: 125
Joined: Thu Apr 12, 2018 9:18 am
Location: New South Wales Australia

Re: Thinking of writing a technical FAQ

Wed Jul 11, 2018 8:47 am

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.

jamesh
Raspberry Pi Engineer & Forum Moderator
Raspberry Pi Engineer & Forum Moderator
Posts: 23867
Joined: Sat Jul 30, 2011 7:41 pm

Re: Thinking of writing a technical FAQ

Wed Jul 11, 2018 9:42 am

Useful to have some instant feedback on specifics - I'll update what I have done so far. Thanks.
Principal Software Engineer at Raspberry Pi (Trading) Ltd.
Contrary to popular belief, humorous signatures are allowed. Here's an example...
“I think it’s wrong that only one company makes the game Monopoly.” – Steven Wright

hippy
Posts: 6068
Joined: Fri Sep 09, 2011 10:34 pm
Location: UK

Re: Thinking of writing a technical FAQ

Wed Jul 11, 2018 1:52 pm

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.

hippy
Posts: 6068
Joined: Fri Sep 09, 2011 10:34 pm
Location: UK

Re: Thinking of writing a technical FAQ

Wed Jul 11, 2018 7:45 pm

Another one for the FAQ -

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

jbudd
Posts: 1016
Joined: Mon Dec 16, 2013 10:23 am

Re: Thinking of writing a technical FAQ

Wed Jul 11, 2018 9:43 pm

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.

jerrm
Posts: 197
Joined: Wed May 02, 2018 7:35 pm

Re: Thinking of writing a technical FAQ

Wed Jul 11, 2018 10:39 pm

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.

hippy
Posts: 6068
Joined: Fri Sep 09, 2011 10:34 pm
Location: UK

Re: Thinking of writing a technical FAQ

Thu Jul 12, 2018 12:19 am

Another -

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

User avatar
bertlea
Posts: 299
Joined: Wed Dec 07, 2016 6:33 am
Location: Hong Kong

Re: Thinking of writing a technical FAQ

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. 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:

ejolson
Posts: 3674
Joined: Tue Mar 18, 2014 11:47 am

Re: Thinking of writing a technical FAQ

Thu Jul 12, 2018 3:20 am

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.

User avatar
bertlea
Posts: 299
Joined: Wed Dec 07, 2016 6:33 am
Location: Hong Kong

Re: Thinking of writing a technical FAQ

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. :(

jamesh
Raspberry Pi Engineer & Forum Moderator
Raspberry Pi Engineer & Forum Moderator
Posts: 23867
Joined: Sat Jul 30, 2011 7:41 pm

Re: Thinking of writing a technical FAQ

Thu Jul 12, 2018 9:30 am

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!
Principal Software Engineer at Raspberry Pi (Trading) Ltd.
Contrary to popular belief, humorous signatures are allowed. Here's an example...
“I think it’s wrong that only one company makes the game Monopoly.” – Steven Wright

jamesh
Raspberry Pi Engineer & Forum Moderator
Raspberry Pi Engineer & Forum Moderator
Posts: 23867
Joined: Sat Jul 30, 2011 7:41 pm

Re: Thinking of writing a technical FAQ

Thu Jul 12, 2018 9:30 am

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....!
Principal Software Engineer at Raspberry Pi (Trading) Ltd.
Contrary to popular belief, humorous signatures are allowed. Here's an example...
“I think it’s wrong that only one company makes the game Monopoly.” – Steven Wright

User avatar
bensimmo
Posts: 4182
Joined: Sun Dec 28, 2014 3:02 pm
Location: East Yorkshire

Re: Thinking of writing a technical FAQ

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/

jamesh
Raspberry Pi Engineer & Forum Moderator
Raspberry Pi Engineer & Forum Moderator
Posts: 23867
Joined: Sat Jul 30, 2011 7:41 pm

Re: Thinking of writing a technical FAQ

Thu Jul 12, 2018 9:46 am

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.
Principal Software Engineer at Raspberry Pi (Trading) Ltd.
Contrary to popular belief, humorous signatures are allowed. Here's an example...
“I think it’s wrong that only one company makes the game Monopoly.” – Steven Wright

DirkS
Posts: 9956
Joined: Tue Jun 19, 2012 9:46 pm
Location: Essex, UK

Re: Thinking of writing a technical FAQ

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.

User avatar
bensimmo
Posts: 4182
Joined: Sun Dec 28, 2014 3:02 pm
Location: East Yorkshire

Re: Thinking of writing a technical FAQ

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.

DirkS
Posts: 9956
Joined: Tue Jun 19, 2012 9:46 pm
Location: Essex, UK

Re: Thinking of writing a technical FAQ

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...

DirkS
Posts: 9956
Joined: Tue Jun 19, 2012 9:46 pm
Location: Essex, UK

Re: Thinking of writing a technical FAQ

Thu Jul 12, 2018 10:16 am

@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

User avatar
piglet
Posts: 911
Joined: Sat Aug 27, 2011 1:16 pm

Re: Thinking of writing a technical FAQ

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/

User avatar
bensimmo
Posts: 4182
Joined: Sun Dec 28, 2014 3:02 pm
Location: East Yorkshire

Re: Thinking of writing a technical FAQ

Thu Jul 12, 2018 10:33 am

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

User avatar
bensimmo
Posts: 4182
Joined: Sun Dec 28, 2014 3:02 pm
Location: East Yorkshire

Re: Thinking of writing a technical FAQ

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
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)

jamesh
Raspberry Pi Engineer & Forum Moderator
Raspberry Pi Engineer & Forum Moderator
Posts: 23867
Joined: Sat Jul 30, 2011 7:41 pm

Re: Thinking of writing a technical FAQ

Thu Jul 12, 2018 10:44 am

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.
Principal Software Engineer at Raspberry Pi (Trading) Ltd.
Contrary to popular belief, humorous signatures are allowed. Here's an example...
“I think it’s wrong that only one company makes the game Monopoly.” – Steven Wright

DirkS
Posts: 9956
Joined: Tue Jun 19, 2012 9:46 pm
Location: Essex, UK

Re: Thinking of writing a technical FAQ

Thu Jul 12, 2018 11:06 am

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...
Last edited by DirkS on Thu Jul 12, 2018 11:17 am, edited 1 time in total.

hippy
Posts: 6068
Joined: Fri Sep 09, 2011 10:34 pm
Location: UK

Re: Thinking of writing a technical FAQ

Thu Jul 12, 2018 11:14 am

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.

Return to “General discussion”