Re: Development Ideas for MediaGoblin's Docs

[jgart]

Hi Ben and Distopico,

Thanks for the feedback. I'll keep your suggestions in mind.

all the best,

jgart

April 26, 2021 1:17 AM, "Ben Sturmfels" <ben@sturm.com.au> wrote:

> Hi Jgart,
> 
> Thanks for the suggestion of mkdocs. Sphinx/reStructuredText is defacto
> standard for the Python community, which means that although it may not
> be perfect, it's familiar to many.
> 
> Technology switches like this need to be really game-changing to justify
> the effort, not to mention breaking a whole lot of existing links. From
> the end-reader's perspective, we'd put in all this effort and they'd see
> no tangible improvement.
> 
> I'd much sooner see yours or others time spent on improving the existing
> documentation or writing more. If you'd like to contribute in this are,
> our plan is to bring the most valuable content across from the wiki into
> the official documentation - we'd appreciate your help. That said, it's
> actually very difficult to write good documentation unless you're very
> familiar with the project, so unlike some people, I don't think it's an
> easy path for a new contributor.
> 
> Regards,
> Ben
> 
> On Sun, 25 Apr 2021, Distopico Vegan wrote:
> 
>> Mediagoblin use sphinx and it support markdown as well and sphinx is
>> more powerful than mkdocs, I don't believe that reStructuredText is a
>> barrier to the contributor in the end both formats have similar
>> structure and many editor also support .rest, maybe for a non dev/tech
>> contributor the wiki could be easier so I think could be better
>> put the effort to restoring the wiki than migrate the docs to another
>> format
>> 
>> On 2021-04-24, jgart wrote:
>> 
>>> Hi Goblineers,
>>> 
>>> What do you think of mediagoblin having markdown for its docs in the future 
>>> instead of
>>> reStructuredText?
>>> 
>>> I was thinking of using MkDocs: https://www.mkdocs.org
>>> 
>>> My motivation for having having mediagoblin's docs in markdown is for 
>>> reasons of accessibility. New
>>> contributors or those not familiar with reST will more than likely feel 
>>> more comfortable making
>>> contributions to mediagoblin docs if they were written in markdown.
>>> 
>>> Most text editors also support markdown syntax so it's likely that a 
>>> beginner would have a higher
>>> probabability of easily finding support for markdown and not run into as 
>>> many issues.
>>> 
>>> Markdown can also be easily previewed in a web browser. It's not as easy to 
>>> find reST
>>> previewers/renderers.
>>> 
>>> 11.2k projects depend on MkDocs on github alone.
>>> 
>>> It would be quite easy to convert the mediagoblin codebase to markdown with 
>>> pandoc.
>>> 
>>> What do you think?
>>> 
>>> jgart
>>> 
>>> ps
>>> 
>>> I'm working on packaging MkDocs for guix. I'll let you know as soon as it's 
>>> merged upstream.