Want to talk about soil? Join us for Open Call every Tuesday until Mar. 30 and our kick-off call on this topic on Feb. 2! Click here for details on how to join!

Public Lab Research note

Wiki Discussion

by Ashan | March 13, 2017 19:36 13 Mar 19:36 | #14010 | #14010

About me

Name: K.A.A Priyadarshana

Email: ashanpriyadarshana@gmail.com

Gitter nick: aspriya

LinkedIn profile: https://www.linkedin.com/in/ashan-priyadarshana-25425282/

Affiliation: Bsc(Hons) in Information Technology, Faculty of Information Technology, University of Moratuwa.

Location: Colombo, Sri Lanka (GMT +5:30)

Phone: +94711005491

Project description

Abstract/summary (<20 words):

Making wiki pages more interactive and discussion-oriented by adding features like commenting, suggesting and tagging special parts of wiki.

Problem

Wiki pages are web pages that anyone can create or edit. We use them to collect information, documentation and instructions on projects. At present we can create wikis, edit them and associate tags with them. But we can not add comments to this, can not make suggestions, can not tag a user for a special part in the wiki. We can make wikis more alive by implementing these features. And as shown in the above diagram, implementing these as in Google docs would be more attractive. For this I will use the publiclab/inline-markdown-editor.

Implementation

After integrating wiki pages with inline-markdown-editor, page of a wiki will be broken down into sections. Then after that i will develop so users can view comments, view suggestion, make comments and make suggestions on those each section. Mockups for those functions are as follows.

Active Sections

When mouse is moved over sections, those will get active and will have a emboss effect to indicate that. And then links/buttons for editing, commenting/suggesting, view comments and view suggestions will be displayed below that active section. A mockup is as follows.

image description

In this mockup second paragraph is the active paragraph (mouse pointer is above that section). And also the way of showing comments of a paragraph is also show here (i.e comments related to fourth paragraph is displayed).

Commenting

When clicked the commenting icon, an inline form will appear below the related paragraph. A user will enter his/her comments and save. And those comments will be shown as in previous image. A mockup to show the entering of comments is as follows.

image description

Suggestions

When clicked the pencil icon, an inline form will appear below the related paragraph. A user will have the ability to edit that section or to make suggestions for that section using this appeared form. And all the contents of the section will automatically be present inside the form, so that the user does not have type content of section in order to edit or suggest. A mockup of that functionality is below.

image description

Viewing suggestions

When clicked the view suggestions button, all the suggestions will get applied to the paragraph and those suggestion parts will be displayed in red color. And all the suggestion will get a number such as [ 1 ]. This will happen automatically so the person who make the suggestion does not have to worry about it. And then there will be options to accept, resolve, and discard those suggestion. A sample mockup is as follows.

image description

Timeline/milestones

image description

Needs

Additional notes or documents regarding wikis would be great. And I need guidance from Public Lab director board and from my mentor.

Setup

Yes I have forked the publiclab/plots2 repository and I have a running version in my local. And I pulled all the updates with remote repository.

Forked repository

And I have setup the publiclab/plots2 in an AWS EC2 instance. I will use this to show my work to mentors. This will be a great help for me and for my mentor to discuss by looking at a live version of publiclab/plots2 with what I have implemented. Following is the IP address of the the account and to view it you can click the link.

http://35.161.83.45:3000/

Experience

Before I attend to university I did course on higher diploma in IT. In there I learned Java, C#, PHP and other most Basic Web Technologies. I learnt fundamental web building blocks from PHP and from codeigniter framework. At University, I moved to ruby and Rails as a web development framework. I have experience in technologies such as Ruby, Java, JavaScript, HTML, CSS, GIT and frameworks/libraries such as Java SDK, Android SDK, CodeIgniter, ASP.net, Ruby on Rails, etc. I also managed to work part time at a company called Vesess which is specialized in web application development, during the 2nd year of my undergraduate course. I mostly worked with technologies like Ruby, RoR, MySQL, GIT, JavaScript etc. In this time period I developed ApistaCRM by using ruby on rails And now I am an Intern at Vesess and contributing to project Hiveage by improving its test cases. Following is the link for ApistaCRM that i have developed.

ApistaCRM

Yes I went through the contributor guidelines and I have good knowledge about Git and I am very much familiar with both GitHub and GitLab. And yes, I have almost contributed to Public Lab

Teamwork

Me as a undergraduate student, teamwork is not a strange thing. In the university for all the academic projects we work as a team. In first year we developed a tv-remote and computer controllable wall clock with another five students. And in second year we developed a mobile app which dispalys web sites attractively, human friendly and which removes advertisements.Both of these projects were one year long and were 5 member groups. So I know that there are barriers, failures and conflicts when working with a team, and also with my experience I know how to manage difficulties and how to communicate with team mates positively.

Passion

As a deep nature lover and an observer, Public Lab always interests me. I always admire the work you guys do. And I started my open source path by this. The first feeling of getting a PR accepted was gained by Public Lab. So Yes, For sure Public Lab always interests me.

Ongoing involvement:

These are my previous contribution to the project

https://github.com/publiclab/plots2/issues/1260

https://github.com/publiclab/plots2/pull/1356

https://github.com/publiclab/plots2/issues/1358

Commitment

Yes I Understood that Importance of this project and I can spend required time period to complete particular task without being time oriented. and since my mentors and me are in completely different time zones I can keep my communication with my mentor organization without any interruptions and delays.

12 Comments

  
Comment Author Profile Picture warren commented almost 4 years ago

This is great to hear, @Ashan -- I've been thinking about how we could use inline tags to make this possible, but it's a challenge. Some things to think about:

  1. if a proposed edit is stored in the text, and applies to a section of text, like the bright [suggest:1234]**eyed fox was**[/suggest] looking for food, then what happens if the text is changes a) inside the tags, b) outside and including the tags, or c) partly outside and partly inside -- like if someone changes bright eyed to dim-witted?
  2. if a comment is made inline (if we allow this), and not on its own paragraph, if the text around it is deleted or changed, does the comment disappear? Or do we try to extract the comment and move it to the end of the line, or something complicated?

There are a lot of places things can go wrong, basically. And if we don't store comments inline in the text, then how do we know where to display them? (This is why I'm suggesting inline comment storage, actually.)

An inline comment might be like:

This person [comment:1234] went to the store.

while one on its own line might be like:

This person went to the store.

[comment:1234]

Then they ate food.

Sorry for my crude examples, but I hope this helps get you thinking about the complexity of this! I /also/ think that we should consider how comments appear while editing a section -- for example with the inline editor: https://github.com/publiclab/inline-markdown-editor

This last editor may also be where we prompt people to actually create comments -- next to the pencil button in the example, there might be a comment button.

This is a lot of info -- what do you think?

Is this a question? Click here to post it to the Questions page.

Reply to this comment...


  
Comment Author Profile Picture Ashan commented almost 4 years ago

Wow, thanks for the feedback. hmm, as you have mentioned for commenting, a small comment button next to pencil button might do the job.

Yes, Due to the mentioned problems inline comment storage seems to be good. I am still thinking and researching about the issues with suggestions as you have mentioned. For a instance we could give notifications if a user is editing texts containing suggestions. But that may not be 100% solution. Have to think and research more on this.

Thanks again for these info. I forked and learning about the inline-markdown-editor. It would be great if you can share some links or notes to understand publiclab/inline-markdown-editor

Reply to this comment...


  
Comment Author Profile Picture warren commented almost 4 years ago

Hi, Ashan - basically with inline-markdown-editor, the idea was to find a very clean abstraction, a way that the code could run with minimal context and complexity, not only on our own platform but potentially on other peoples' markdown content as well. So after thinking a long time about it, we took the model that it can be run on any markdown string, to both display (and parse) the markdown as HTML, but also insert editor forms after each section. Then each editor form would be able to submit a before and after request for replacing just that section of content. This isn't quite as flexible as Google Docs, but it's a clean API that can be tested and built on.

So I think commenting and suggesting could follow similar paths, whether or not they're developed as extensions of the inline-markdown-editor -- the key is if their behavior is easily testable, and is separable from the rest of the PublicLab.org code. See how inline-markdown-editor has very clear and minimal points of interface -- the incoming markdown, and the "replacement" API call to a url like /wiki/replace?before=aaa&after=bbb?

That makes our code more maintainable, easier to read and understand, and more re-usable (so perhaps other projects would start to use it and help maintain it).

For comments, for example, when we render the wiki page in plots2, we'd go through the raw markdown the way we do with the inline tags, and find/replace those codes with a more fully-fledged form. But we could also try to do this in JavaScript, in theory, like we do with the inline-markdown-editor. What are the pros and cons?

Thanks!

Is this a question? Click here to post it to the Questions page.

Reply to this comment...


  
Comment Author Profile Picture Ashan commented almost 4 years ago

Thanks Warren. These past few days I was exploring the inline-markdown-editor. Its approach is clean and understandable. So yes I think implementing the wiki's commenting and suggesting features like that is good. As now I'm confident with current implementation codes of wiki and with inline-markdown-editor codes, in coming days I'm willing to work on some previous issues regarding wiki. That should help me understand more and contribute.

As for pros and cons you asked, I see much of pros. Because implementing these features as inline-markdown-editor is good for future use. Because we have a separate module in case of any new comer to understand how it is implemented.

Thank you very much again

Reply to this comment...


  
Comment Author Profile Picture warren commented almost 4 years ago

Thank you very much for your thoughtful and thorough mockups. I have some thoughts which I hope to add today as I take a 2nd trip, apologies for the delay in providing feedback!

One thing for starters is -- who would be able to resolve/accept/discard a suggestion?

OK, more soon!

Is this a question? Click here to post it to the Questions page.

Reply to this comment...


  
Comment Author Profile Picture Ashan commented almost 4 years ago

Yes, That's a main thing to think about. I was thinking the original user who posted the wiki, moderators and admin are good candidates for this ability. Because as any user can edit the wiki, the person who makes a suggestion could simply edit it. But the reason he makes a suggestion may be:

  1. Person is not sure if he/she is correct
  2. He want that change to be done by the original user
  3. Or for some other personal reason.

So I think resolve/accept/discard abilities should be given to author, moderator and admin.

Thanks for your feedback and time. Please give any feedback as I'm very happy to know and correct my errors.

Reply to this comment...


  
Comment Author Profile Picture warren commented almost 4 years ago

OK, so for the UI, there's a lot going on here, and I think we may want to start with one thing at a time, rather than trying to do all the UI work up front. I'm thinking, for example, about the suggestion selector as you've shown it -- how do we know what the suggested change applies to? Would the user select text?

How about having suggest be an alternative to editing, rather than commenting. That way, suggestions could be posed as a change to the entire subsection -- and to view a suggestion, you'd see a diff? So to propose one, you get an editor just as you would the usual inline editor, but you'd have either "Save" or "Suggest changes" -- that way there'd be fewer interface options too, since they'd share the pencil button.

What do you think?

Is this a question? Click here to post it to the Questions page.

Reply to this comment...


  
Comment Author Profile Picture warren commented almost 4 years ago

You're right that they could simply edit themselves. What if we show the "resolve" options to everyone, but with a small notice that says something like @person is making a suggestion so that others can provide input before accepting the change. You may either accept it or leave a comment on the section to discuss the changes with them.

Reply to this comment...


  
Comment Author Profile Picture Ashan commented almost 4 years ago

Thanks @warren for the feedback.

  1. A suggestion can be applied to a certain set words to indicate that it's good that they are changed like in the suggestion. ex: the [bright][suggest:1234] vivid [/suggest] eyed fox was looking for food. So here instead of word bright, a users suggests word vivid. This is a one type of suggestion.

  2. A suggestion may be added by a user to indicate that suggested words should be added to that place. ex: the bright eyed [suggest:1234] hungry [/suggest] fox was looking for food. So, here there is no selection of words. User just suggests that word hungry should be inserted there. Notice that there are no [ ] symbols to indicate that this suggestion is not attached to any words.

  3. A suggestion may be added by a user to indicate that a certain word/words should be removed. That can be done as following example. the [bright eyed] [suggest:1234] [/suggest] fox was looking for food. So in here, the suggestion applies to word bright eyed, and suggested word is a blank space. So this indicates the suggestion of removal of bright eyed words.

So to select words that a suggestion applies, I thought of use of [ and ] symbols is good. Is it good? or should I think of another way?

Thanks again for your great feedbacks, they are very helpful for me to think in correct path.

Is this a question? Click here to post it to the Questions page.

Reply to this comment...


  
Comment Author Profile Picture Ashan commented almost 4 years ago

Yes that's a good idea. Making suggestions as a alternative to editing seems to be more accurate, because at both times we will have to load the contents of the section to editor. So yes I will move it under the pencil button. Thanks for the feedback.

And yes as you have indicated showing the resolve option to everyone is also good. But could you explain me a little bit more about it. Because I'm not sure if I got the idea 100%. thanks.

Reply to this comment...


  
Comment Author Profile Picture warren commented almost 4 years ago

For [bright][suggest:1234] vivid [/suggest], I think that may run into collisions if you want to change, for example, the word "suggest" (haha) -- so maybe:

[suggest:1234] bright [to] vivid [/suggest] (acknowledging that this markup would not typically be directly edited; it'd be generated by our UI)

Does that make sense? Then removal could be like:

[suggest:1234] bright [to] [/suggest]

However, we might want to start with the interface as I described where you make edits and it does a suggestion to the whole paragraph rather than asking people to select/replace individual words (just as a simpler model to attempt first) and then once we're more confident in it, develop ideas and a UI for replacing at a finer level of detail, like individual words.

I think it may be hard to anticipate all the possible failure cases with such a complex feature -- for example, preventing improperly nested suggestions, and managing broken ones if someone inadvertently breaks one like [/sugges t] -- which could cause chaos. There are lots of possible problems we'll have to try out and write good tests for! It's probably a good idea to start collecting these test ideas now.

As for the resolve option, i think you're right in terms of who it's probably targeted at. But it's hard to know, and maybe people will want to resolve their own (i do this sometimes on Google Docs). So by showing a short text message to help people understand that it is a suggestion, we don't /stop/ people from resolving it, but we hopefully offer enough explanation for what a suggestion is intended for so that the right people are the ones to actually /use/ it.

Thanks for your thoughtful responses and changes! Much appreciated.

Is this a question? Click here to post it to the Questions page.

Reply to this comment...


  
Comment Author Profile Picture Ashan commented almost 4 years ago

Wow, that did not come to my mind!. yes of course that way there would be a problem. And [suggest:1234] bright [to] vivid [/suggest] would not run into such problems. Thanks @werren very much for pointing out it to me.

Yep I will be thinking and try out some test for possible problems that could happen.

again, thank you very much for your feedback.

Reply to this comment...


Login to comment.

Share

Public Lab is open for anyone and will always be free. By signing up you'll join a diverse group of community researchers and tap into a lot of grassroots expertise.

Sign up