Re: Development Ideas for MediaGoblin's Docs

[Ben Sturmfels]

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.