Re: restarting our FAQ

[Dirk Hohndel via subsurface]

After a couple more hours of playing with this...

> On Feb 8, 2022, at 2:26 PM, Dirk Hohndel  wrote:
>> 
>> That's exactly what github wikis are: a collection of markdown files managed 
>> in a git repository. If you login to your account, you should see a link to 
>> clone the wiki locally. Should be something like:
>> 
>> https://github.com/subsurface/subsurface.wiki.git 
>> 
> 
> That is fascinating. I have to create that first page for this to work - but 
> I played with it in your wiki and that does seem like a reasonable 
> compromise. If we assume that we don't want to deal with translations, this 
> is maybe an easier way to go.

Well, maybe not. The options are "anyone can edit a wiki page" (sorry, been 
there, done that, HECK NO), or "the same group of users that can edit the wiki 
also have push access to the repo" (sorry, that's an idiotic equivalency). So 
I'm afraid the access control for wikis on GitHub is just not at the level that 
I'd need to be comfortable with this.

> 
>> As far as I know, there is no interface for PRs, but you can always publish 
>> it as a normal repo in the project, and then manually push to the wiki repo 
>> to publish changes. It might even be possible to automate that last part 
>> with a github action?
> 
> Yeah - but likely that would get us back to the place that we're in with the 
> GitHub.io  page. Because fundamentally - either I allow 
> people to edit the wiki (so I give people like Jason edit rights to the wiki) 
> - or I do this via the PR interface and then I might as well build GitHub.io 
>  pages. There really wouldn't be any difference.
> 
> So I'll have to take a look at how easy it would be to have a group of users 
> whom I give write access to the wiki. And I'll use you and Jason as guinea 
> pigs for this - just to give this a try :)

Since this didn't work, I'll play with other ways to get close to this.

Maybe the simple answer is not to have the complex "accordion" style FAQ but 
instead do far simpler pages that feel much more like a wiki and that are 
easier to edit for casual contributors - but with decent access controls... 
which brings me back to needing to figure out an easier way to create a PR for 
the GitHub.io pages.

Sometimes it feels like I'm running in circles :)

/D___
subsurface mailing list
subsurface@subsurface-divelog.org
http://lists.subsurface-divelog.org/cgi-bin/mailman/listinfo/subsurface

Re: restarting our FAQ

[Dirk Hohndel via subsurface]

> On Feb 8, 2022, at 1:16 PM, Jef Driesen  wrote:
> 
> On 8/02/2022 21:54, Dirk Hohndel via subsurface wrote:
>> I haven't spent any time at all on the GitHub wiki setup to know how easily 
>> we could curate this and more importantly how easily one can create useful 
>> deep links to specific answers that could be posted into email / the forum. 
>> I understand very well how to manage submissions to the GitHub.io 
>>  page through PRs.
>> I need to spend time to understand how that would work with the wiki. 
>> Because the very last thing I need on earth is another time sucking task.
>> I'd still likely be leaning towards just a set of markdown pages on the 
>> GitHub.io  site instead of a wiki - but that's mainly 
>> because I haven't done the work to investigate how that would really work.
> 
> That's exactly what github wikis are: a collection of markdown files managed 
> in a git repository. If you login to your account, you should see a link to 
> clone the wiki locally. Should be something like:
> 
> https://github.com/subsurface/subsurface.wiki.git

That is fascinating. I have to create that first page for this to work - but I 
played with it in your wiki and that does seem like a reasonable compromise. If 
we assume that we don't want to deal with translations, this is maybe an easier 
way to go.

> As far as I know, there is no interface for PRs, but you can always publish 
> it as a normal repo in the project, and then manually push to the wiki repo 
> to publish changes. It might even be possible to automate that last part with 
> a github action?

Yeah - but likely that would get us back to the place that we're in with the 
GitHub.io page. Because fundamentally - either I allow people to edit the wiki 
(so I give people like Jason edit rights to the wiki) - or I do this via the PR 
interface and then I might as well build GitHub.io pages. There really wouldn't 
be any difference.

So I'll have to take a look at how easy it would be to have a group of users 
whom I give write access to the wiki. And I'll use you and Jason as guinea pigs 
for this - just to give this a try :)

Thanks for pushing in this direction. Because the easier I make this, the more 
likely I'll be to get strong help.

/D___
subsurface mailing list
subsurface@subsurface-divelog.org
http://lists.subsurface-divelog.org/cgi-bin/mailman/listinfo/subsurface

Re: restarting our FAQ

[Jef Driesen via subsurface]

On 8/02/2022 21:54, Dirk Hohndel via subsurface wrote:
I haven't spent any time at all on the GitHub wiki setup to know how easily we 
could curate this and more importantly how easily one can create useful deep 
links to specific answers that could be posted into email / the forum. I 
understand very well how to manage submissions to the GitHub.io 
 page through PRs.
I need to spend time to understand how that would work with the wiki. Because 
the very last thing I need on earth is another time sucking task.


I'd still likely be leaning towards just a set of markdown pages on the 
GitHub.io  site instead of a wiki - but that's mainly because 
I haven't done the work to investigate how that would really work.


That's exactly what github wikis are: a collection of markdown files managed in 
a git repository. If you login to your account, you should see a link to clone 
the wiki locally. Should be something like:


https://github.com/subsurface/subsurface.wiki.git

I'm using this for libdivecomputer, and so far it works well for me.

As far as I know, there is no interface for PRs, but you can always publish it 
as a normal repo in the project, and then manually push to the wiki repo to 
publish changes. It might even be possible to automate that last part with a 
github action?


Jef
___
subsurface mailing list
subsurface@subsurface-divelog.org
http://lists.subsurface-divelog.org/cgi-bin/mailman/listinfo/subsurface

Re: restarting our FAQ

[Dirk Hohndel via subsurface]

We used to have a wiki which I shut down when I averaged 50 spam user creations 
and more than a thousand attempted spam posts a day.
I spent more time trying to deal with that than with Subsurface itself.

Maybe that's better with GitHub wikis. Who knows.

I am ok with saying that the FAQ is English only.

I haven't spent any time at all on the GitHub wiki setup to know how easily we 
could curate this and more importantly how easily one can create useful deep 
links to specific answers that could be posted into email / the forum. I 
understand very well how to manage submissions to the GitHub.io page through 
PRs.
I need to spend time to understand how that would work with the wiki. Because 
the very last thing I need on earth is another time sucking task.

I'd still likely be leaning towards just a set of markdown pages on the 
GitHub.io site instead of a wiki - but that's mainly because I haven't done the 
work to investigate how that would really work.

I guess another task to add to my list, eh?

/D

> On Feb 8, 2022, at 11:51 AM, Crawford Currie wrote:
> 
> Do you really need to translate the FAQ? FAQs are normally used to try to 
> stop support channels from getting choked with trivia. I see questions on the 
> subsurface forum  falling 
> into three broad categories:
> questions that should be answered by RTFM
> questions that relate to specific hosts / dive computers
> questions that are too deep for the doc
> - RTFM questions should be addressed by accessible, easy to consume 
> documentation, and the project already does that really well,
> 
> - Deep questions is what I think the forum should really be about, which 
> leaves:
> 
> - Specific hosts / dive computers. This is a constantly moving target, as 
> dive computer tech moves forward apace, and trying to maintain a translated 
> FAQ for the dozens of brands and models out there does not sound like an 
> efficient use of developer or translator time.
> 
> Personally I'm not a fan of tablets-of-stone FAQs anyway, as they rarely 
> answer my questions and just end up being a source of frustration. What is 
> frequently asked today may not be so frequently asked next year - but the 
> answers to last year's questions may still be relevant to someone.
> 
> For long-tail projects like Subsurface, I much prefer the stackoverflow 
> approach, where answers can come from anyone and spam is dealt with by user 
> moderation. Failing that, a wiki (again with user moderation) can also work, 
> though it requires more work from the dev team to define and maintain an 
> effective taxonomy.
> 
> With respect to translation, anyone seriously looking for answers is quite 
> capable of pasting into Google Translate. ;-)
> 

___
subsurface mailing list
subsurface@subsurface-divelog.org
http://lists.subsurface-divelog.org/cgi-bin/mailman/listinfo/subsurface

Re: restarting our FAQ

[Crawford Currie via subsurface]

Do you really need to translate the FAQ? FAQs are normally used to try 
to stop support channels from getting choked with trivia. I see 
questions on the subsurface forum 
 falling into three 
broad categories:


1. questions that should be answered by RTFM
2. questions that relate to specific hosts / dive computers
3. questions that are too deep for the doc

- RTFM questions should be addressed by accessible, easy to consume 
documentation, and the project already does that really well,


- Deep questions is what I think the forum should really be about, which 
leaves:


- Specific hosts / dive computers. This is a constantly moving target, 
as dive computer tech moves forward apace, and trying to maintain a 
translated FAQ for the dozens of brands and models out there does not 
sound like an efficient use of developer or translator time.


Personally I'm not a fan of tablets-of-stone FAQs anyway, as they rarely 
answer my questions and just end up being a source of frustration. What 
is frequently asked today may not be so frequently asked next year - but 
the answers to last year's questions may still be relevant to someone.


For long-tail projects like Subsurface, I much prefer the stackoverflow 
approach, where answers can come from anyone and spam is dealt with by 
user moderation. Failing that, a wiki (again with user moderation) can 
also work, though it requires more work from the dev team to define and 
maintain an effective taxonomy.


With respect to translation, anyone seriously looking for answers is 
quite capable of pasting into Google Translate. ;-)


C.


On 08/02/2022 16:57, Dirk Hohndel via subsurface wrote:

Hi Crawford,

I thought about this - but that makes translations a lot more awkward. 
And we have seen in the past that we have far more luck getting people 
to contribute to things where they can simply edit text and send a 
PR... admittedly, that may be self-selection bias :)


/D


On Feb 8, 2022, at 12:32 AM, Crawford Currie via subsurface wrote:

Just a thought, but wouldn't it be easier to just use the project wiki?

https://github.com/subsurface/subsurface/wiki

C.

On 08/02/2022 01:33, Dirk Hohndel via subsurface wrote:

Hi everyone

The FAQ on the old website is horribly out of date and hasn't been maintained 
in forever.
Instead of trying to deal with the completely defunct WordPress site (the 
website is actually a static export of the old WordPress site since I was 
unable to keep up with the thousands of automated hacking attempts) I created a 
new FAQ for our GitHub pages.

Which means everyone can contribute!

The syntax is... an acquired taste - I'm sure there would have been a better 
way to do this. But hey, it works.

This is the user visible site:https://subsurface.github.io/faq/
And this is where the sources 
are:https://github.com/subsurface/subsurface.github.io/blob/master/faq.MD?plain=1

I'd love feedback, improvements, contributions.

Thanks

/D


___
subsurface mailing list
subsurface@subsurface-divelog.org
http://lists.subsurface-divelog.org/cgi-bin/mailman/listinfo/subsurface

Re: restarting our FAQ

[Dirk Hohndel via subsurface]

Hi Peter,

> On Feb 8, 2022, at 1:05 AM, Peter Zaal  wrote:
> 
> Looks fine to me, but I am in no way an UI expert. I noticed a lot of the old 
> items are removed, but I guess these are all addressed in the documentation. 
> Maybe add a small note or add to the 'Other questions' on the FAQ page to 
> search in the documentation first ?

Yes, this was a "few hours of work" in order to get started with something and 
get feedback.
For example - I visually like the folding structure, but it makes things harder 
to edit. And this way we can't have convenient deep links.
So maybe we should just do a flat file? Or maybe I'm wrong in disagreeing with 
Crawford and we should just do a Wiki?

> A small grammar thing: some item titles start with a capital letter, some do 
> not. They are written like a sentence, so they should start with a capital 
> letter. Same for the 'answer' text.

Yes, Jason already submitted a PR that fixed that :)

> How would this work for localization, can there be faq.MD's in the language 
> subfolders and will they be shown if the user selects a specific language?

Correct, that was the idea that brought me down this path...

/D
___
subsurface mailing list
subsurface@subsurface-divelog.org
http://lists.subsurface-divelog.org/cgi-bin/mailman/listinfo/subsurface

Re: restarting our FAQ

[Dirk Hohndel via subsurface]

Hi Crawford,

I thought about this - but that makes translations a lot more awkward. And we 
have seen in the past that we have far more luck getting people to contribute 
to things where they can simply edit text and send a PR... admittedly, that may 
be self-selection bias :)

/D

> On Feb 8, 2022, at 12:32 AM, Crawford Currie via subsurface wrote:
> 
> Just a thought, but wouldn't it be easier to just use the project wiki?
> 
> https://github.com/subsurface/subsurface/wiki 
> 
> 
> C.
> 
> On 08/02/2022 01:33, Dirk Hohndel via subsurface wrote:
>> Hi everyone
>> 
>> The FAQ on the old website is horribly out of date and hasn't been 
>> maintained in forever.
>> Instead of trying to deal with the completely defunct WordPress site (the 
>> website is actually a static export of the old WordPress site since I was 
>> unable to keep up with the thousands of automated hacking attempts) I 
>> created a new FAQ for our GitHub pages.
>> 
>> Which means everyone can contribute!
>> 
>> The syntax is... an acquired taste - I'm sure there would have been a better 
>> way to do this. But hey, it works.
>> 
>> This is the user visible site: https://subsurface.github.io/faq/ 
>> 
>> And this is where the sources are: 
>> https://github.com/subsurface/subsurface.github.io/blob/master/faq.MD?plain=1
>>  
>> 
>> 
>> I'd love feedback, improvements, contributions.
>> 
>> Thanks
>> 
>> /D

___
subsurface mailing list
subsurface@subsurface-divelog.org
http://lists.subsurface-divelog.org/cgi-bin/mailman/listinfo/subsurface

Re: restarting our FAQ

[Peter Zaal via subsurface]

Hi,

Looks fine to me, but I am in no way an UI expert. I noticed a lot of the
old items are removed, but I guess these are all addressed in the
documentation. Maybe add a small note or add to the 'Other questions' on
the FAQ page to search in the documentation first ?
A small grammar thing: some item titles start with a capital letter, some
do not. They are written like a sentence, so they should start with a
capital letter. Same for the 'answer' text.
How would this work for localization, can there be faq.MD's in the
language subfolders and will they be shown if the user selects a specific
language?

Peter


On Tue, Feb 8, 2022 at 2:33 AM Dirk Hohndel via subsurface <
subsurface@subsurface-divelog.org> wrote:

>
> Hi everyone
>
> The FAQ on the old website is horribly out of date and hasn't been
> maintained in forever.
> Instead of trying to deal with the completely defunct WordPress site (the
> website is actually a static export of the old WordPress site since I was
> unable to keep up with the thousands of automated hacking attempts) I
> created a new FAQ for our GitHub pages.
>
> Which means everyone can contribute!
>
> The syntax is... an acquired taste - I'm sure there would have been a
> better way to do this. But hey, it works.
>
> This is the user visible site: https://subsurface.github.io/faq/
> And this is where the sources are:
> https://github.com/subsurface/subsurface.github.io/blob/master/faq.MD?plain=1
>
> I'd love feedback, improvements, contributions.
>
> Thanks
>
> /D
> ___
> subsurface mailing list
> subsurface@subsurface-divelog.org
> http://lists.subsurface-divelog.org/cgi-bin/mailman/listinfo/subsurface
>
___
subsurface mailing list
subsurface@subsurface-divelog.org
http://lists.subsurface-divelog.org/cgi-bin/mailman/listinfo/subsurface

Re: restarting our FAQ

[Crawford Currie via subsurface]

Just a thought, but wouldn't it be easier to just use the project wiki?

https://github.com/subsurface/subsurface/wiki

C.

On 08/02/2022 01:33, Dirk Hohndel via subsurface wrote:

Hi everyone

The FAQ on the old website is horribly out of date and hasn't been maintained 
in forever.
Instead of trying to deal with the completely defunct WordPress site (the 
website is actually a static export of the old WordPress site since I was 
unable to keep up with the thousands of automated hacking attempts) I created a 
new FAQ for our GitHub pages.

Which means everyone can contribute!

The syntax is... an acquired taste - I'm sure there would have been a better 
way to do this. But hey, it works.

This is the user visible site:https://subsurface.github.io/faq/
And this is where the sources 
are:https://github.com/subsurface/subsurface.github.io/blob/master/faq.MD?plain=1

I'd love feedback, improvements, contributions.

Thanks

/D
___
subsurface mailing list
subsurface@subsurface-divelog.org
http://lists.subsurface-divelog.org/cgi-bin/mailman/listinfo/subsurface



--
Crawford Currie
/SCUBA Instructor, Hartford Sub-Aqua Club 
Taijiquan Instructor, Chenjigou Taijiquan GB 
/

07837 877956___
subsurface mailing list
subsurface@subsurface-divelog.org
http://lists.subsurface-divelog.org/cgi-bin/mailman/listinfo/subsurface