[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Development Ideas for MediaGoblin's Docs

From: jgart
Subject: Re: Development Ideas for MediaGoblin's Docs
Date: Wed, 28 Apr 2021 17:11:48 +0000

Hi Ben and Distopico,

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

all the best,


April 26, 2021 1:17 AM, "Ben Sturmfels" <> 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:
>>> 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.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]