[Scummvm-devel] Reigniting our docs effort

[Matan Bareket]

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/

[Alex Bevilacqua]

Using Sphinx and rst for this is a great idea. I've used the MongoDB docs
as a template for this type of initiative in the past (
https://docs.mongodb.com). All their source and build instructions are on
GitHub if anyone's curious (https://github.com/mongodb/docs).

Post by Matan Bareket
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.
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.
https://docs.phpmyadmin.net/en/latest/
http://docs.godotengine.org/en/3.0/
_______________________________________________
Scummvm-devel mailing list
http://lists.scummvm.org/listinfo/scummvm-devel

[Eugene Sandulenko]

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

Post by Matan Bareket
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.
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.
https://docs.phpmyadmin.net/en/latest/
http://docs.godotengine.org/en/3.0/
_______________________________________________
Scummvm-devel mailing list
http://lists.scummvm.org/listinfo/scummvm-devel

[Matan Bareket]

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.

Post by Eugene Sandulenko
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

Post by Matan Bareket
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.
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.
https://docs.phpmyadmin.net/en/latest/
http://docs.godotengine.org/en/3.0/
_______________________________________________
Scummvm-devel mailing list
http://lists.scummvm.org/listinfo/scummvm-devel

[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

Post by Matan Bareket
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.

Post by Eugene Sandulenko
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

Post by Matan Bareket
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.
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.
https://docs.phpmyadmin.net/en/latest/
http://docs.godotengine.org/en/3.0/
_______________________________________________
Scummvm-devel mailing list
http://lists.scummvm.org/listinfo/scummvm-devel

[Matan Bareket]

1. Sphinx can export as both PDF, EPUB and HTML. We can impose a style
guide that will impose a 79 characters line length in the source files
(when rendered, line breaks are ignored between rows and paragraphs are
separated by an empty line)
2. Yes, I see our FAQ being much much smaller with a proper doc site.
here's an example of a FAQ structure and links:
http://docs.readthedocs.io/en/latest/faq.html#my-project-isn-t-building-with-autodoc

Post by Eugene Sandulenko
Okay.
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

Post by Matan Bareket
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.

Post by Eugene Sandulenko
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

Post by Matan Bareket
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.
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.
https://docs.phpmyadmin.net/en/latest/
http://docs.godotengine.org/en/3.0/
_______________________________________________
Scummvm-devel mailing list
http://lists.scummvm.org/listinfo/scummvm-devel

[Lothar Serra Mari]

This all sounds very good to me. Let me know if you need any assistence.

Lothar

Post by Matan Bareket
1. Sphinx can export as both PDF, EPUB and HTML. We can impose a style
guide that will impose a 79 characters line length in the source files
(when rendered, line breaks are ignored between rows and paragraphs are
separated by an empty line)
2. Yes, I see our FAQ being much much smaller with a proper doc site.
http://docs.readthedocs.io/en/latest/faq.html#my-project-isn-t-building-with-autodoc

Post by Eugene Sandulenko
Okay.
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

Post by Matan Bareket
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.

Post by Eugene Sandulenko
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

Post by Matan Bareket
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.
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.
https://docs.phpmyadmin.net/en/latest/
http://docs.godotengine.org/en/3.0/
_______________________________________________
Scummvm-devel mailing list
http://lists.scummvm.org/listinfo/scummvm-devel

_______________________________________________
Scummvm-devel mailing list
http://lists.scummvm.org/listinfo/scummvm-devel

[Matan Bareket]

Thanks Lothar,
I'm hoping making to docs more accessible to editors will encourage
everyone on the team to contribute!

Eugene, with your blessing I'd like to start and create the docs repo and
copy (but not move) some of our existing docs into it as is, then start
editorializing it into a proper manual.

Post by Lothar Serra Mari
This all sounds very good to me. Let me know if you need any assistence.
Lothar

Post by Matan Bareket
1. Sphinx can export as both PDF, EPUB and HTML. We can impose a style
guide that will impose a 79 characters line length in the source files
(when rendered, line breaks are ignored between rows and paragraphs are
separated by an empty line)
2. Yes, I see our FAQ being much much smaller with a proper doc site.

http://docs.readthedocs.io/en/latest/faq.html#my-project-isn-t-building-with-autodoc

Post by Matan Bareket

Post by Eugene Sandulenko
Okay.
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

Post by Matan Bareket
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

Post by Matan Bareket

Post by Eugene Sandulenko

Post by Matan Bareket
together into something more cohesive.
Some of the FAQ is redundant today, for example the introduction

section,

Post by Matan Bareket

Post by Eugene Sandulenko

Post by Matan Bareket
supported games section, parts of running games - all of these are

covered

Post by Matan Bareket

Post by Eugene Sandulenko

Post by Matan Bareket
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

Post by Matan Bareket

Post by Eugene Sandulenko

Post by Matan Bareket
rest.

Post by Eugene Sandulenko
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

Post by Matan Bareket

Post by Eugene Sandulenko

Post by Matan Bareket

Post by Eugene Sandulenko
covered anywhere else.
Eugene

Post by Matan Bareket
Team,
I want to try and reignite our documentation effort which will
eventually consolidate all of the disparate docs we have (doxygen,

site

Post by Matan Bareket

Post by Eugene Sandulenko

Post by Matan Bareket

Post by Eugene Sandulenko

Post by Matan Bareket
pages, quickstart, wiki, readme) into one central location.
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

Post by Matan Bareket

Post by Eugene Sandulenko

Post by Matan Bareket

Post by Eugene Sandulenko

Post by Matan Bareket
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

Post by Matan Bareket

Post by Eugene Sandulenko

Post by Matan Bareket

Post by Eugene Sandulenko

Post by Matan Bareket
to work off.
There are a few doxygen to sphinx parsers, but it's more of a phase

2.

Post by Matan Bareket

Post by Eugene Sandulenko

Post by Matan Bareket

Post by Eugene Sandulenko

Post by Matan Bareket
Hopefully getting everything we have now into one central location

that

Post by Matan Bareket

Post by Eugene Sandulenko

Post by Matan Bareket

Post by Eugene Sandulenko

Post by Matan Bareket
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

Post by Matan Bareket

Post by Eugene Sandulenko

Post by Matan Bareket

Post by Eugene Sandulenko

Post by Matan Bareket
sidebar. We can potentially host everything ourselves if it's a big

issue.

Post by Matan Bareket

Post by Eugene Sandulenko

Post by Matan Bareket

Post by Eugene Sandulenko

Post by Matan Bareket
https://docs.phpmyadmin.net/en/latest/
http://docs.godotengine.org/en/3.0/
_______________________________________________
Scummvm-devel mailing list
http://lists.scummvm.org/listinfo/scummvm-devel

_______________________________________________
Scummvm-devel mailing list
http://lists.scummvm.org/listinfo/scummvm-devel

_______________________________________________
Scummvm-devel mailing list
http://lists.scummvm.org/listinfo/scummvm-devel