[Scummvm-devel] Reigniting our docs effort

[Eugene Sandulenko]

Okay.

I have a couple of questions then:

  1. Will it be possible to export the result into an 80-columns text
format, so we could ship it as part of the distribution?
  2. Would it be possible to have fixed reference URLs for the relevant FAQ
items?


Eugene

On 9 August 2018 at 12:26, Matan Bareket <mataniko at gmail.com> wrote:

> I'm proposing to start with converting both the User Manual and the README
> to the new format as sort of a v.1 and then start editing everything
> together into something more cohesive.
>
> Some of the FAQ is redundant today, for example the introduction section,
> supported games section, parts of running games - all of these are covered
> either in the manual or the README. Other parts are not.
>
> Eventually the new docs hub should cover most of the FAQ and migrate the
> rest.
>
> On Thu, Aug 9, 2018 at 2:11 AM Eugene Sandulenko <sev at scummvm.org> wrote:
>
>> The idea to renew the documentation is always nice.
>>
>> Which one are you referring to? Our README? Our User Manual?
>>
>> Why do you think, FAQ is redundant? I do not remember its content being
>> covered anywhere else.
>>
>>
>> Eugene
>>
>> On 7 August 2018 at 22:28, Matan Bareket <mataniko at gmail.com> wrote:
>>
>>> Team,
>>>
>>> I want to try and reignite our documentation effort which will
>>> eventually consolidate all of the disparate docs we have (doxygen, site
>>> pages, quickstart, wiki, readme) into one central location.
>>>
>>> In order to do so, i'd like to do the following:
>>>
>>>    1. Create a new repo called scummvm-docs
>>>    2. Convert existing docs into reStructredText - Initial pass won't
>>>    make much sense but it will be a good place to work off.
>>>    3. Eliminate redundant information - For example the FAQ on the
>>>    website. The wiki will be focused on more developer related items.
>>>    4. Use readthedocs to host & manage docs
>>>
>>> A few notes: https://readthedocs.org/ is a free service that takes care
>>> of the headaches of managing by automatically synchronizing with the docs
>>> repo. It also uses Sphinx to create the documentation, it also supports
>>> multiple languages so we can hook it up to weblate for translators to work
>>> off.
>>>
>>> There are a few doxygen to sphinx parsers, but it's more of a phase 2.
>>>
>>> Hopefully getting everything we have now into one central location that
>>> can be easily updated via git will encourage active work on our docs.
>>>
>>> One caveat to readthedocs is that they place a single ethical ad on the
>>> sidebar. We can potentially host everything ourselves if it's a big issue.
>>>
>>> Some sample sites on readthedocs:
>>> https://docs.phpmyadmin.net/en/latest/
>>> http://docs.godotengine.org/en/3.0/
>>>
>>>
>>>
>>> _______________________________________________
>>> Scummvm-devel mailing list
>>> Scummvm-devel at lists.scummvm.org
>>> http://lists.scummvm.org/listinfo/scummvm-devel
>>>
>>>
>>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.scummvm.org/pipermail/scummvm-devel/attachments/20180809/57a88a6a/attachment.html>