Re: New wiki painful to use

Re: New wiki painful to use

[dnl]

[-- Attachment #1: Type: text/plain, Size: 444 bytes --]

Hi,
I've not used the new wiki and while I like the idea of using markup in theory I can imagine the frustration of using it regularly.


I didn't want to say this earlier as Michael seemed keen to write his own wiki, but have you considered using Atlassian confluence? It's free for open source software https://www.atlassian.com/software/views/open-source-license-request 

They may even host a copy on their cloud if you want.

dnl

Re: New wiki painful to use

[Michael Tremer]

[-- Attachment #1: Type: text/plain, Size: 1239 bytes --]

Hi dnl,

> On 13 Aug 2019, at 02:06, dnl <dnlipfire(a)runbox.co> wrote:
> 
> Hi,
> I've not used the new wiki and while I like the idea of using markup in theory I can imagine the frustration of using it regularly.

The markup is plain markdown, so many people who use GitHub, other wiki software or write technical documentation are used to it.

I agree that there should be some UI that helps with it because sometimes it is a little bit complicated to type it.

> I didn't want to say this earlier as Michael seemed keen to write his own wiki, but have you considered using Atlassian confluence? It's free for open source software https://www.atlassian.com/software/views/open-source-license-request 

We do not outsource anything to anybody else. So many people have made had bad experiences it. The last thing was GitHub which suddenly wasn’t on “the good side”(TM) any more.

We have the resources and plenty of reasons to host this ourselves and therefore will.

> They may even host a copy on their cloud if you want.
> 
> dnl
> _______________________________________________
> Documentation mailing list
> Documentation(a)lists.ipfire.org
> https://lists.ipfire.org/mailman/listinfo/documentation

Re: New wiki painful to use

[Michael Tremer]

[-- Attachment #1: Type: text/plain, Size: 3959 bytes --]

Hello,

I know that you did not intend this as such, but I am a little angry with your email.

So I hope that we can work this out and that I can explain why things are as they are at the moment and what I am going to do about it.

First of all: There is no time to work on this. I have been doing nothing else but infrastructure and admin work around the project for the last four weeks. I am barely able to respond to my email. One emergency after the other is happening and I am doing “quick and dirty” on more things than I would like to. Bare this in mind. This is also the reason why I am a bit on the edge.

> On 12 Aug 2019, at 22:42, Jon Murphy <jcmurphy26(a)gmail.com> wrote:
> 
> In my opinion: I feel you’re going to see a drop-off of user written wiki pages.  The new wiki is very painful to use!  (I do understand there are not many users writing wiki pages.)

We have virtually nobody contributing to the wiki. There are a couple of reasons. The technical one is that nobody can register an account. Some people have asked for it and never edited a single line. I think many people see a wiki as a read-only kind of data source. Something that I think Wikipedia has created. People just see it as a book. And you simply don’t edit books.

So, this cannot really get worse in my opinion. But this is not news either. A couple of years ago we have thrown away all translations into which some people have put a lot of effort, but they are old, outdated, unmaintained and confused people even more. I think that that is true for a lot of the English wiki as well and my personal opinion here is to just throw it away. False information is worse than none.

> Most of this is related to the lack of a user interface with built-in shortcuts for bold, italics, links, code blocks, etc.  The wiki really needs a proper user interface like what was available with the old wiki or what is available with the forum.

On that: I have said that the wiki was stitched together a little bit. It was an experiment that has become reality now. It is work in progress. I have asked for feedback and I got little. I do not think that many open points were left that could have easily been implemented. This is why I wasn’t too happy to read this email now, because I would have preferred some constructive ideas and help over this now.

> Is there not another wiki to fit the need?  Like a competitor to Dokuwiki? I’d hate to think the IPFire firewall devs would need to be spending their time creating a new wiki.  

I would absolutely not have gone through this work if I thought that there was anything out there. All projects I have checked out use outdated or custom software. Web software has died a very ugly death recently. We have the same problem with the forum.

In the end it is easier to put a wiki together on our own than spending hours and hours of customising some software that breaks as soon as you install an update (i.e. our forum which is now un-themed and unpatched for a very long time).

So this is the basis we have to work with right now.

> Did the https://github.com/benweet/stackedit.js not work?

This project hasn’t been updated in years. I am not going to integrate legacy software into something new.

> Nothing written above is meant to hurt anyone’s feelings or make anyone mad.  I’m just personally frustrated working in the new wiki environment knowing I’ve only touched 80 pages and we have 300+ pages to go!  Ugh!

I am not taking it as such, but I share your frustration. I am also quite frustrated about seeing loads of HTML and only the word “update” in the change log. This is not how this was intended and we have talked about why this is a bad idea.

-Michael

> 
> Jon
> 
> _______________________________________________
> Documentation mailing list
> Documentation(a)lists.ipfire.org
> https://lists.ipfire.org/mailman/listinfo/documentation

Re: New wiki painful to use

[Jon Murphy]

[-- Attachment #1: Type: text/plain, Size: 3080 bytes --]


> I have asked for feedback and I got little. I do not think that many open points were left that could have easily been implemented. This is why I wasn’t too happy to read this email now, because I would have preferred some constructive ideas and help over this now.


You are a tough person to send feedback to.  You have a tendency to react in off-putting ways.  Re-read your response.

You did receive my constructive ideas in the Documentation list.



> First of all: There is no time to work on this. I have been doing nothing else but infrastructure and admin work around the project for the last four weeks. I am barely able to respond to my email. One emergency after the other is happening and I am doing “quick and dirty” on more things than I would like to. Bare this in mind. This is also the reason why I am a bit on the edge.

How can I help?  

Since I’m not a firewall expert, I help with documentation (I started working on the old wiki near April 2018)



> False information is worse than none.

Sorry to say but you’ll have to point those out (I know you are busy!).  I’m not an expert but I have been going through and correcting what I can.  I don’t have the skills to identify false info. 



>> Did the https://github.com/benweet/stackedit.js not work?
> 
> This project hasn’t been updated in years. I am not going to integrate legacy software into something new.

Sorry for dwelling on this (and I’m not trying to make you mad):
To my unskilled eyes it looks like it was updated in Aug 2018.  I saw your concern about PageDown but there is not a Pagedown reference in the JS code.  On the webpage it states "stackedit.js is lightweight and has no dependency.” (I wrote a note to the developer to confirm).  I am missing something obvious...



> I am also quite frustrated about seeing loads of HTML .... This is not how this was intended and we have talked about why this is a bad idea.

What should I correct?  The HTML I remember is:

    <color blue> Example </color> to <span style=“color:blue”> Example </span>

I believe I wrote to you asking for guidance and did not receive a response.

Keep in mind, pages that look like this —> https://wiki.ipfire.org/hardware/arm?revision=2019-08-06T13:57:34.868460

Will now look like this —> https://wiki.ipfire.org/hardware/arm?revision=2019-01-09T19:34:43

—

I’m sure you realize this is an uphill battle.  Especially since users are allowed/encouraged to update wiki pages.  Without the code to limit or exclude HTML you’ll become the wiki cop and continue to be frustrated by non-compliance.  This doesn’t seem worth your time.


> I am also quite frustrated about ... only the word “update” in the change log.

Look at the revisions for a single page.  You see many proper remarks.  The “Update” is normally a quick change where I got frustrated fighting the interface to get a page completed.  My bad.  I will do better.



Again, none of this is meant to be mean.  It just my feedback.

Re: New wiki painful to use

[Michael Tremer]

[-- Attachment #1: Type: text/plain, Size: 5538 bytes --]

Hi,

> On 15 Aug 2019, at 21:51, Jon Murphy <jcmurphy26(a)gmail.com> wrote:
> 
> 
>> I have asked for feedback and I got little. I do not think that many open points were left that could have easily been implemented. This is why I wasn’t too happy to read this email now, because I would have preferred some constructive ideas and help over this now.
> 
> 
> You are a tough person to send feedback to.  You have a tendency to react in off-putting ways.  Re-read your response.
> 
> You did receive my constructive ideas in the Documentation list.

I told you why those are not possible to be implemented.

>> First of all: There is no time to work on this. I have been doing nothing else but infrastructure and admin work around the project for the last four weeks. I am barely able to respond to my email. One emergency after the other is happening and I am doing “quick and dirty” on more things than I would like to. Bare this in mind. This is also the reason why I am a bit on the edge.
> 
> How can I help?  
> 
> Since I’m not a firewall expert, I help with documentation (I started working on the old wiki near April 2018)

Writing documentation is very helpful.

> 
> 
> 
>> False information is worse than none.
> 
> Sorry to say but you’ll have to point those out (I know you are busy!).  I’m not an expert but I have been going through and correcting what I can.  I don’t have the skills to identify false info. 

Okay, I will put this on my list.

>From the top of my mind I know that we have some add-ons on the wiki that we have dropped a long time ago. Some of those pages have a note that the feature has been dropped. I think there is no reason to keep those pages.

>>> Did the https://github.com/benweet/stackedit.js not work?
>> 
>> This project hasn’t been updated in years. I am not going to integrate legacy software into something new.
> 
> Sorry for dwelling on this (and I’m not trying to make you mad):
> To my unskilled eyes it looks like it was updated in Aug 2018.  I saw your concern about PageDown but there is not a Pagedown reference in the JS code.  On the webpage it states "stackedit.js is lightweight and has no dependency.” (I wrote a note to the developer to confirm).  I am missing something obvious…

Stackedit.js is not an option at all. It just embeds an iframe and loads load of stuff from the Internet.

I do not want to send any user content to an untrusted third party. We also have infrastructure documentation in this wiki and nobody needs to know this. They even log for which page you are sending a request. Madness that it isn’t even documented anywhere.

So I wrote something lightweight and easy in less than 200 lines of JS code (could be 50 lines without comments, etc.). It has the following features:

* You can highlight text and then mark it as bold, italic, code or make a headline or link out of it
* You can use keyboard shortcuts which I find very neat, because you don’t have to move your hands away from your keyboard. Hover over the icons to see the shortcuts.

Let me know if I forgot anything.

There is also a link to the “files” section now so that you can upload images with a few clicks only.

I only tested this in Safari and FF. So there might be problems with other browsers. IE? No idea. Feedback is of course appreciated.

> 
>> I am also quite frustrated about seeing loads of HTML .... This is not how this was intended and we have talked about why this is a bad idea.
> 
> What should I correct?  The HTML I remember is:
> 
>    <color blue> Example </color> to <span style=“color:blue”> Example </span>
> 
> I believe I wrote to you asking for guidance and did not receive a response.

Please do not use *any* HTML.

Please do not use any colours. They create barriers for people who cannot see them.

> Keep in mind, pages that look like this —> https://wiki.ipfire.org/hardware/arm?revision=2019-08-06T13:57:34.868460
> 
> Will now look like this —> https://wiki.ipfire.org/hardware/arm?revision=2019-01-09T19:34:43

Yes, I am aware of that. The page can be organised in a different way so it does not rely on those colours.

> I’m sure you realize this is an uphill battle.  Especially since users are allowed/encouraged to update wiki pages.  Without the code to limit or exclude HTML you’ll become the wiki cop and continue to be frustrated by non-compliance.  This doesn’t seem worth your time.

I am not fighting any battles here. In case someone turns against our mission that is a serious problem. We can have an argument, that is something totally different.

Users are very much encouraged to update the wiki. I think it could not be easier now. Nobody needs to have any skill apart from word.

Writing some markup syntax is in the nature of a wiki (see Wikipedia) and it works.

>> I am also quite frustrated about ... only the word “update” in the change log.
> 
> Look at the revisions for a single page.  You see many proper remarks.  The “Update” is normally a quick change where I got frustrated fighting the interface to get a page completed.  My bad.  I will do better.

No need to write a novel here. Three words can be enough. It just should be clear that the page has not only changed but what (and maybe why if it isn’t just some syntax stuff).

> Again, none of this is meant to be mean.  It just my feedback.

I didn’t take it like that. Please keep it coming.

Best,
-Michael

Re: New wiki painful to use

[Jon Murphy]

[-- Attachment #1: Type: text/plain, Size: 1992 bytes --]


> 
> So I wrote something lightweight and easy in less than 200 lines of JS code (could be 50 lines without comments, etc.). It has the following features:
> 
> * You can highlight text and then mark it as bold, italic, code or make a headline or link out of it
> * You can use keyboard shortcuts which I find very neat, because you don’t have to move your hands away from your keyboard. Hover over the icons to see the shortcuts.
> 
> Let me know if I forgot anything.
> 
> There is also a link to the “files” section now so that you can upload images with a few clicks only.
> 
> I only tested this in Safari and FF. So there might be problems with other browsers. IE? No idea. Feedback is of course appreciated.

Looks good!  I’ll give it a try and report back.

—

Is there a way to search for image names?  It can be a console/terminal command or anything that helps.  For now it doesn’t need to be an easy button or anything.  There are many images I cannot locate.

Missing Images (quick examples):
- lcd4linux_ipfire-specific-widget.jpg
- configuration_logs_url-filter_log.png
- netfilter-packet-flow.svg.png
- squidclamav-detection.png
- addons_icecast_using.png
- etc...

> 
>> 
>>> I am also quite frustrated about seeing loads of HTML .... This is not how this was intended and we have talked about why this is a bad idea.
>> 
>> What should I correct?  The HTML I remember is:
>> 
>>   <color blue> Example </color> to <span style=“color:blue”> Example </span>
>> 
>> I believe I wrote to you asking for guidance and did not receive a response.
> 
> Please do not use *any* HTML.
> 
> Please do not use any colours. They create barriers for people who cannot see them.

Currently all of the links are red and those will be very difficult to see for people that are red/green color blind.  May need to change to purple (or some other color that is color blind friendly.

I’ll begin to remove the color/span code.

Re: New wiki painful to use

[Michael Tremer]

[-- Attachment #1: Type: text/plain, Size: 2645 bytes --]

Hi,

> On 27 Aug 2019, at 16:54, Jon Murphy <jcmurphy26(a)gmail.com> wrote:
> 
> 
>> 
>> So I wrote something lightweight and easy in less than 200 lines of JS code (could be 50 lines without comments, etc.). It has the following features:
>> 
>> * You can highlight text and then mark it as bold, italic, code or make a headline or link out of it
>> * You can use keyboard shortcuts which I find very neat, because you don’t have to move your hands away from your keyboard. Hover over the icons to see the shortcuts.
>> 
>> Let me know if I forgot anything.
>> 
>> There is also a link to the “files” section now so that you can upload images with a few clicks only.
>> 
>> I only tested this in Safari and FF. So there might be problems with other browsers. IE? No idea. Feedback is of course appreciated.
> 
> Looks good!  I’ll give it a try and report back.
> 
> —
> 
> Is there a way to search for image names?  It can be a console/terminal command or anything that helps.  For now it doesn’t need to be an easy button or anything.  There are many images I cannot locate.
> 
> Missing Images (quick examples):
> - lcd4linux_ipfire-specific-widget.jpg
> - configuration_logs_url-filter_log.png
> - netfilter-packet-flow.svg.png
> - squidclamav-detection.png
> - addons_icecast_using.png
> - etc…

None of these exist in the database.

We do not have any search for images. I am not sure if it would help to search on the filename, because often they are not very useful.

>>>> I am also quite frustrated about seeing loads of HTML .... This is not how this was intended and we have talked about why this is a bad idea.
>>> 
>>> What should I correct?  The HTML I remember is:
>>> 
>>>  <color blue> Example </color> to <span style=“color:blue”> Example </span>
>>> 
>>> I believe I wrote to you asking for guidance and did not receive a response.
>> 
>> Please do not use *any* HTML.
>> 
>> Please do not use any colours. They create barriers for people who cannot see them.
> 
> Currently all of the links are red and those will be very difficult to see for people that are red/green color blind.  May need to change to purple (or some other color that is color blind friendly.

People who are colourblind will be able to see the link.

It is just impossible for some people who cannot distinguish some shades of green or red if their ARM board is supported.

> I’ll begin to remove the color/span code.

Thank you.

Maybe we should have a list at the top with supported boards and then the second half of the page can be the non-supported boards?

-Michael

Re: New wiki painful to use

[Jon Murphy]

[-- Attachment #1: Type: text/plain, Size: 608 bytes --]

Michael - Is this what you are looking for?
 

https://wiki.ipfire.org/hardware/arm/playground

It is split into three different Tables:
	• Well Supported (was green before)
	• Basic support (was yellow before)
	• 'Does not work' and 'Does not work and no support planned' (was red and black before)

Here is the old page with colors:
https://wiki.ipfire.org/hardware/arm


> 
>> I’ll begin to remove the color/span code.
> 
> Thank you.
> 
> Maybe we should have a list at the top with supported boards and then the second half of the page can be the non-supported boards?
> 

Re: New wiki painful to use

[Michael Tremer]

[-- Attachment #1: Type: text/plain, Size: 787 bytes --]

Hi,

Yes, I think this works. What do you think?

-Michael

> On 3 Sep 2019, at 23:19, Jon Murphy <jcmurphy26(a)gmail.com> wrote:
> 
> Michael - Is this what you are looking for?
> 
> 
> https://wiki.ipfire.org/hardware/arm/playground
> 
> It is split into three different Tables:
> 	• Well Supported (was green before)
> 	• Basic support (was yellow before)
> 	• 'Does not work' and 'Does not work and no support planned' (was red and black before)
> 
> Here is the old page with colors:
> https://wiki.ipfire.org/hardware/arm
> 
> 
>> 
>>> I’ll begin to remove the color/span code.
>> 
>> Thank you.
>> 
>> Maybe we should have a list at the top with supported boards and then the second half of the page can be the non-supported boards?
>> 
> 

Re: New wiki painful to use

[Jon Murphy]

[-- Attachment #1: Type: text/plain, Size: 1344 bytes --]

Honestly?  I think it is too 'flat' and lacks color.  The original table was almost perfect.


Suggestions:

Use Harvey balls - https://en.wikipedia.org/wiki/Harvey_balls
-or-
Use Okto symbols - https://en.wikipedia.org/wiki/Okta
-or-
Something similar to Consumer Reports rating symbols:
https://www.consumerreports.org/video/view/inside-labs/5131824875001/our-ratings--consumer-reports/


And it should include color.  <—-- One of those things we disagree on

EDIT - added mailing list.

> 
> 
> Hi,
> 
> Yes, I think this works. What do you think?
> 
> -Michael
> 
>> On 3 Sep 2019, at 23:19, Jon Murphy <jcmurphy26(a)gmail.com> wrote:
>> 
>> Michael - Is this what you are looking for?
>> 
>> 
>> https://wiki.ipfire.org/hardware/arm/playground
>> 
>> It is split into three different Tables:
>> 	• Well Supported (was green before)
>> 	• Basic support (was yellow before)
>> 	• 'Does not work' and 'Does not work and no support planned' (was red and black before)
>> 
>> Here is the old page with colors:
>> https://wiki.ipfire.org/hardware/arm
>> 
>> 
>>> 
>>>> I’ll begin to remove the color/span code.
>>> 
>>> Thank you.
>>> 
>>> Maybe we should have a list at the top with supported boards and then the second half of the page can be the non-supported boards?
>>> 
>> 
> 

Re: New wiki painful to use

[Tom Rymes]

[-- Attachment #1: Type: text/plain, Size: 1979 bytes --]

I'm with John on this one, the modified version is inferior. I get that 
we need to be conscious of color-blindness, but the new version doesn't 
work for anyone. May I suggest:

Green Checkmark: Very well supported.
Empty Yellow Circle: Basic Support.
Red "X": Does not work.
Universal Prohibition Symbol: Does not work and no support planned.

Tom

On 09/05/2019 4:52 PM, Jon Murphy wrote:
> Honestly?  I think it is too 'flat' and lacks color.  The original table was almost perfect.
> 
> 
> Suggestions:
> 
> Use Harvey balls - https://en.wikipedia.org/wiki/Harvey_balls
> -or-
> Use Okto symbols - https://en.wikipedia.org/wiki/Okta
> -or-
> Something similar to Consumer Reports rating symbols:
> https://www.consumerreports.org/video/view/inside-labs/5131824875001/our-ratings--consumer-reports/
> 
> 
> And it should include color.  <—-- One of those things we disagree on
> 
> EDIT - added mailing list.
> 
>>
>>
>> Hi,
>>
>> Yes, I think this works. What do you think?
>>
>> -Michael
>>
>>> On 3 Sep 2019, at 23:19, Jon Murphy <jcmurphy26(a)gmail.com> wrote:
>>>
>>> Michael - Is this what you are looking for?
>>>
>>>
>>> https://wiki.ipfire.org/hardware/arm/playground
>>>
>>> It is split into three different Tables:
>>> 	• Well Supported (was green before)
>>> 	• Basic support (was yellow before)
>>> 	• 'Does not work' and 'Does not work and no support planned' (was red and black before)
>>>
>>> Here is the old page with colors:
>>> https://wiki.ipfire.org/hardware/arm
>>>
>>>
>>>>
>>>>> I’ll begin to remove the color/span code.
>>>>
>>>> Thank you.
>>>>
>>>> Maybe we should have a list at the top with supported boards and then the second half of the page can be the non-supported boards?
>>>>
>>>
>>
> 
> _______________________________________________
> Documentation mailing list
> Documentation(a)lists.ipfire.org
> https://lists.ipfire.org/mailman/listinfo/documentation
> 

Re: New wiki painful to use

[Michael Tremer]

[-- Attachment #1: Type: text/plain, Size: 2863 bytes --]

Hi,

I disagree on the colour. Not because of the colour-blindness argument, but rather that we are writing technical documentation here. How appealing it looks is rather less important to me. It is more important to deliver the information and present it in a way that it is accessible to as many people as possible and there is no room for misinterpretation.

Visually I find the big table more appealing as well.

On the pictogram thing. What about using unicode characters for this?

We could rate the boards with stars? ★ to ★★★★★?

How about that?

-Michael

> On 5 Sep 2019, at 22:23, Tom Rymes <trymes(a)rymes.com> wrote:
> 
> I'm with John on this one, the modified version is inferior. I get that we need to be conscious of color-blindness, but the new version doesn't work for anyone. May I suggest:
> 
> Green Checkmark: Very well supported.
> Empty Yellow Circle: Basic Support.
> Red "X": Does not work.
> Universal Prohibition Symbol: Does not work and no support planned.
> 
> Tom
> 
> On 09/05/2019 4:52 PM, Jon Murphy wrote:
>> Honestly?  I think it is too 'flat' and lacks color.  The original table was almost perfect.
>> Suggestions:
>> Use Harvey balls - https://en.wikipedia.org/wiki/Harvey_balls
>> -or-
>> Use Okto symbols - https://en.wikipedia.org/wiki/Okta
>> -or-
>> Something similar to Consumer Reports rating symbols:
>> https://www.consumerreports.org/video/view/inside-labs/5131824875001/our-ratings--consumer-reports/
>> And it should include color.  <—-- One of those things we disagree on
>> EDIT - added mailing list.
>>> 
>>> 
>>> Hi,
>>> 
>>> Yes, I think this works. What do you think?
>>> 
>>> -Michael
>>> 
>>>> On 3 Sep 2019, at 23:19, Jon Murphy <jcmurphy26(a)gmail.com> wrote:
>>>> 
>>>> Michael - Is this what you are looking for?
>>>> 
>>>> 
>>>> https://wiki.ipfire.org/hardware/arm/playground
>>>> 
>>>> It is split into three different Tables:
>>>> 	• Well Supported (was green before)
>>>> 	• Basic support (was yellow before)
>>>> 	• 'Does not work' and 'Does not work and no support planned' (was red and black before)
>>>> 
>>>> Here is the old page with colors:
>>>> https://wiki.ipfire.org/hardware/arm
>>>> 
>>>> 
>>>>> 
>>>>>> I’ll begin to remove the color/span code.
>>>>> 
>>>>> Thank you.
>>>>> 
>>>>> Maybe we should have a list at the top with supported boards and then the second half of the page can be the non-supported boards?
>>>>> 
>>>> 
>>> 
>> _______________________________________________
>> Documentation mailing list
>> Documentation(a)lists.ipfire.org
>> https://lists.ipfire.org/mailman/listinfo/documentation
> _______________________________________________
> Documentation mailing list
> Documentation(a)lists.ipfire.org
> https://lists.ipfire.org/mailman/listinfo/documentation