Re: Inclusivity Issues for new contributors

[Lukas Atkinson <opensource-3R968MVE1sOAz21JXljZEw@public.gmane.org>]

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

It's so cool that you have an Open Source class! There also was a similar
review from you class here
<https://groups.google.com/d/msg/pandoc-discuss/SCNaNRT7484/4exwbELFAAAJ>.

On issue 1: I think the documentation clearly covers the Pandoc-specific
parts. It cannot be a guide that starts from zero. However, a short mention
of what cabal and stack are might be useful for people new to Haskell.

On issue 2: the documentation shows how to run the tests – but not how to
create them. I think a short example that mentions "pandoc -t native" would
already be helpful (this was not obvious to me when I tried hacking on
internals).

On issue 3: pandoc is many things to many people, but fundamentally it is a
compiler. Those are routinely implemented as command line tools, which
makes them easy to integrate into other software. I think a GUI would be
out of scope for the project – any GUI would effectively be a fully fledged
text editor. There are many projects that do provide some Pandoc user
interface, including the Stackedit web app, editor plugins, or
Rstudio/Knitr. The documentation links to various pandoc-related tools
under the entry “extras <https://github.com/jgm/pandoc/wiki/Pandoc-Extras>”.

I'm also not sure front end devs would be the main audience, as opposed to
academics?


On Tue, 21 May 2019 at 19:44, Aseem Prashar <prashara-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 am opening this discussion thread to facilitate conversation on
> inclusivity within the Pandoc project.
>
> *Issue 1:* Our cognitive walk-through found that contributing to Pandoc
> page (https://github.com/jgm/pandoc/blob/master/CONTRIBUTING.md) doesn’t
> give enough information
> on how to set up the environment and start contributing to people who are
> new to open source to encourage them to contribute to this project.
>
> *Issue 2:* The documentation should also provide more instructions on
> setting up the test environment as most people contributing to open source
> for the first time will not be familiar with
> the testing methods used. The documentation on what kind of test is done
> and how to test new features should also be included.
>
> *Issue 3: *This tool is mainly for front end developers, but it has been
> implemented as a command line program, making a GUI for the tool will make
> using this tool easier and faster.
>
> Thank you for reading, looking forward to your responses.
>
> --
> 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/7231afe1-fd0a-4e7d-93ce-fadb9030a244%40googlegroups.com
> <https://groups.google.com/d/msgid/pandoc-discuss/7231afe1-fd0a-4e7d-93ce-fadb9030a244%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/CAJTYOd0Z8YcgVwRdPg_MM52RMaXq-FEJoSHqNPUZmtbpr%3Dj26g%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

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