Inclusivity for novice/new contributors

Inclusivity for novice/new contributors

[Kenneth Wayne Hall III]

[-- Attachment #1.1: Type: text/plain, Size: 1682 bytes --]

Hi everyone!

Oregon State University's Free/Open Source Software class has us evaluate 
real-world open-source projects for inclusivity using a cognitive 
walk-through technique.
I'm opening this discussion post to facilitate conversation on inclusivity 
within the Pandoc project.  Our cognitive walk-through found that the 
installer page (https://github.com/jgm/pandoc/blob/2.7.2/INSTALL.md) had 
jargon and assumed advanced knowledge that was not inclusive of the persona 
which was the subject of our evaluation.  See, for example, instructions on 
installing using Chocolatey, Homebrew that are limited to "install pandoc 
using Chocolatey/Homebrew."  There are links provided to these respective 
tools, but our walk-through found that it is likely that a new person 
looking to get involved would be more likely to be discouraged rather than 
dive into finding out more about Chocolatey/Homebrew.  The LaTex setup 
instructions could also be a bit more detailed.

Thank you for reading, and look forward to hearing what you all have to say 
about possible ways to improve the project's accessibility!

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/52c65e4a-e909-4531-a71e-775fb722c261%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[-- Attachment #1.2: Type: text/html, Size: 2231 bytes --]

Re: Inclusivity for novice/new contributors

[Brandon Keith Biggs]

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

Hello,
Well, the best thing would be to have a server that runs pandoc and a UI
where you can upload and or edit documents in the browser.
Second would be a Markdown and bibtex UI that is like a markdown rich text
editor or text editor that exports and imports all pandoc files.
As it currently stands, Pandoc is commandline only and only accessible to
those who know what a commandline is.
Thanks,


Brandon Keith Biggs <http://brandonkeithbiggs.com/>


On Tue, May 14, 2019 at 12:14 PM Kenneth Wayne Hall III <
hallkenn-e/prDBdGCFNcusGGlJDZ6w@public.gmane.org> wrote:

> Hi everyone!
>
> Oregon State University's Free/Open Source Software class has us evaluate
> real-world open-source projects for inclusivity using a cognitive
> walk-through technique.
> I'm opening this discussion post to facilitate conversation on inclusivity
> within the Pandoc project.  Our cognitive walk-through found that the
> installer page (https://github.com/jgm/pandoc/blob/2.7.2/INSTALL.md) had
> jargon and assumed advanced knowledge that was not inclusive of the persona
> which was the subject of our evaluation.  See, for example, instructions on
> installing using Chocolatey, Homebrew that are limited to "install pandoc
> using Chocolatey/Homebrew."  There are links provided to these respective
> tools, but our walk-through found that it is likely that a new person
> looking to get involved would be more likely to be discouraged rather than
> dive into finding out more about Chocolatey/Homebrew.  The LaTex setup
> instructions could also be a bit more detailed.
>
> Thank you for reading, and look forward to hearing what you all have to
> say about possible ways to improve the project's accessibility!
>
> --
> You received this message because you are subscribed to the Google Groups
> "pandoc-discuss" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
> To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/pandoc-discuss/52c65e4a-e909-4531-a71e-775fb722c261%40googlegroups.com
> <https://groups.google.com/d/msgid/pandoc-discuss/52c65e4a-e909-4531-a71e-775fb722c261%40googlegroups.com?utm_medium=email&utm_source=footer>
> .
> For more options, visit https://groups.google.com/d/optout.
>

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/CAKAWQkVdXrnvJU0BcVDuv-SQ_d%2BEYD%2Bc-7%2BWm7RxBgi5cXNRWg%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

[-- Attachment #2: Type: text/html, Size: 4412 bytes --]

Re: Inclusivity for novice/new contributors

[John MacFarlane]

I would think that the most relevant place to look
would be our "Getting started page"

https://pandoc.org/getting-started.html

This tries to be pretty basic.

The Installing pandoc page,

https://pandoc.org/installing.html

has a gigantic button to download an installer
for your platform.  True, if you read down, you hear
about chocolatey.  That is highly relevant information
for some users who use chocolatey.  But you can
ignore it if you don't; it's text you get to only if
you read on after the big install button and "For
alternative ways to install pandoc, see below..."

Kenneth Wayne Hall III <hallkenn-e/prDBdGCFNcusGGlJDZ6w@public.gmane.org>
writes:

> Hi everyone!
>
> Oregon State University's Free/Open Source Software class has us evaluate 
> real-world open-source projects for inclusivity using a cognitive 
> walk-through technique.
> I'm opening this discussion post to facilitate conversation on inclusivity 
> within the Pandoc project.  Our cognitive walk-through found that the 
> installer page (https://github.com/jgm/pandoc/blob/2.7.2/INSTALL.md) had 
> jargon and assumed advanced knowledge that was not inclusive of the persona 
> which was the subject of our evaluation.  See, for example, instructions on 
> installing using Chocolatey, Homebrew that are limited to "install pandoc 
> using Chocolatey/Homebrew."  There are links provided to these respective 
> tools, but our walk-through found that it is likely that a new person 
> looking to get involved would be more likely to be discouraged rather than 
> dive into finding out more about Chocolatey/Homebrew.  The LaTex setup 
> instructions could also be a bit more detailed.
>
> Thank you for reading, and look forward to hearing what you all have to say 
> about possible ways to improve the project's accessibility!
>

Re: Inclusivity for novice/new contributors

[dmccunney]

On Tue, May 14, 2019 at 3:14 PM Kenneth Wayne Hall III
<hallkenn-e/prDBdGCFNcusGGlJDZ6w@public.gmane.org> wrote:
>
> I'm opening this discussion post to facilitate conversation on inclusivity within the Pandoc project.  Our cognitive walk-through found that the installer page (https://github.com/jgm/pandoc/blob/2.7.2/INSTALL.md) had jargon and assumed advanced knowledge that was not inclusive of the persona which was the subject of our evaluation.

What persona *is* the subject of your evaluation?  I think of Pandoc
as an advanced tool, and people with call to use it in the first place
can reasonably be expected to possess various background knowledge.

What sort of background and experience are you assuming for the
hypothetical user who is the subject of your investigation?

As John mentioned, Pandoc provides installers for various platforms,
and does not *require* Chocolatey/Homebrew to install.  Those
references are provided for folks who already *use* those tools and
may prefer to use them instead of the provided installers to get
Pandoc on their systems.
______
Dennis

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/CAF4AJDyk%2BECnz1AJ7SZ4brBaWR2H8VbkQzHbuuZnLu8R%2B2BXvg%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

Re: Inclusivity for novice/new contributors

[BPJ]

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

What about a pair of intermediate headings "'Easy installation' -> 'The
easiest way to install Pandoc is to download an appropriate installer for
your operating system:' -> List with links to installers for Windows, Mac,
Linux in that order", "'Advanced installation' -> everything else", so that
the easier path for a newbie is more prominently visible as such? That
ought to make most real or imagined person(a)s happy, right?

In my role as a documentation writer/translator for systems which usually
are aimed at non-technical users but with more or less optional advanced
features this is what we do all the time. We call that first section the
"Dummies section" between ourselves (no offense intended, since a big part
of our job is to make sure that all users find the information appropriate
for their level; there is often a "Nerd section" too!) Usually the most
advanced stuff is put in a box with an icon and/or heading meaning "For
advanced/technical users" to alert the "ordinary" user that they should
ignore/skip it rather than try and fail to follow/make sense of it and be
scared off.

Den tis 14 maj 2019 22:53dmccunney <dennis.mccunney-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> skrev:

> On Tue, May 14, 2019 at 3:14 PM Kenneth Wayne Hall III
> <hallkenn-e/prDBdGCFNcusGGlJDZ6w@public.gmane.org> wrote:
> >
> > I'm opening this discussion post to facilitate conversation on
> inclusivity within the Pandoc project.  Our cognitive walk-through found
> that the installer page (
> https://github.com/jgm/pandoc/blob/2.7.2/INSTALL.md) had jargon and
> assumed advanced knowledge that was not inclusive of the persona which was
> the subject of our evaluation.
>
> What persona *is* the subject of your evaluation?  I think of Pandoc
> as an advanced tool, and people with call to use it in the first place
> can reasonably be expected to possess various background knowledge.
>
> What sort of background and experience are you assuming for the
> hypothetical user who is the subject of your investigation?
>
> As John mentioned, Pandoc provides installers for various platforms,
> and does not *require* Chocolatey/Homebrew to install.  Those
> references are provided for folks who already *use* those tools and
> may prefer to use them instead of the provided installers to get
> Pandoc on their systems.
> ______
> Dennis
>
> --
> You received this message because you are subscribed to the Google Groups
> "pandoc-discuss" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
> To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/pandoc-discuss/CAF4AJDyk%2BECnz1AJ7SZ4brBaWR2H8VbkQzHbuuZnLu8R%2B2BXvg%40mail.gmail.com
> .
> For more options, visit https://groups.google.com/d/optout.
>

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/CADAJKhDGUP7npoMg2crahH_NH0A3Q6OjzJAv0w7OM2as2qU0uA%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

[-- Attachment #2: Type: text/html, Size: 5097 bytes --]

Inclusivity for novice/new contributors

[Kolen Cheung]

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

I grew you guys started the evaluation from the wrong place. Probably start from pandoc.org rather than GitHub.com/jgm/pandoc. I wonder if anything can make this more explicit.

But pandoc is a very complicated beast. For what it is capable, it is almost impossible for anyone to learn it quick and be able to contribute.

[IMO you guys put on an “inclusivity” glass learnt from your class and judged wrong. It is better to evaluate something when put into perspective (which should be true for anything from social science and I guess your class is from?)]

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/5be931c4-7e54-4b9a-b4e6-21b4812925dd%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Inclusivity for novice/new contributors

[EBkysko]

[-- Attachment #1.1: Type: text/plain, Size: 3508 bytes --]

Hi,

From your post, and the other from your classmate, you talk about 
"inclusivity for novice/new contributors" to an open source project.

There are at least two ways to contribute to such a project:

i) *Passively*, as a user who encounters bugs in the program, or who sees 
ways that it could be improved, and communicates those comments the 
developers.

In this case you mostly have to get the right information on how to install 
the program. As JMcF has said, the main site pandoc.org/Getting Started is 
better suited for those instructions.

The manual is quite detailed and "inclusive" for a *user *imho.


ii) *Actively*, as a coder who wants to contribute directly to the source 
code.

As said by KCheung in the other post, here the main obstacle is the 
programming language Haskell, which might not be in your curriculum, and it 
might not be within your personal interests to learn something which might 
only be needed for this one project (while others could see this as an 
opportunity to learn "one more language" as a pure hobby).

So here you can't really enter as a newbie... you gotta know a good bit of 
the language... *unless you want to use the project to learn the language*... 
personally, pandoc is the *only* program I know/use that uses Haskell.

So you gotta already have some kind of enthusiasm to learn by yourself 
(with the help of online info or some downloaded books) and roll up your 
sleeves.


But in fact, there's a third option also in the case of Pandoc:

iii) *Semi-actively*, program what pandoc can do through Lua programming, 
since pandoc allows you to change some internal/intermediate 
behavior/structures, and even allows you to create your own "output writer".

Here again you have to learn a new programming language you might not have 
known, Lua. It an easier language to learn, and it's at least used (to my 
limited knowledge) elsewhere: programming within games, within graphical 
programs like GIMP, programming within (La)TeX, etc. And you won't have to 
learn Haskell (although a peak at the Haskell code can give you hints...).

Here the documentation for Lua filters and Lua "custom writers" could be 
better and more welcoming to newcomers, but the people(s) involved have a 
lot to do "in real life" and I'm sure they did what they could for now.

Most of the times I've found answers to my questions on this Pandoc 
GoogleGroups, Pandoc Github issue pages, StackOverflow, and some other 
places... *"Google is your f(r)iend"*. Like in so many cases, in any 
project, you have to find answers by yourself here and there, and even 
create your own answers... It can be frustrating at times, rewarding at 
others.


So, in conclusion, depending on your needs and ambitions and curiosity, any 
open source project can be an opportunity to better yourself, to challenge 
yourself to learn some new stuff, and most of the times there won't be 
someone to hold your hand.

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/06cdecf8-2fd1-43ce-9660-207e7acae5d3%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[-- Attachment #1.2: Type: text/html, Size: 4154 bytes --]