[LEDE-DEV] Lede/Openwrt documentation

[Javier Domingo Cansino]

I will suppose all the proposals are accepted when answering

> I see this can be a good way forward, but I have some questions.
>
> I still think user-level documentation must have a decent wiki-like editor
> in the browser, because github's editor
> sucks big way, and isn't suited for proper formatting and similar. I'm not
> that happy with docuwiki's editor (current editor) either.
> Does your proposed system have something like that?

I'm afraid there is no online editing as in dokuwiki.

This system would work through PRs in github, and the user could link
"Edit this file in github", which would direct him to the file, and
there he would be able to click on "Fork and edit", and then submit a
pull request. The process is not optimal for really sparse
contributions, but I believe it can help to maintain documental
integrity.

Also, if desired I can configure sphinx with markdown support, so that
Markdown can be used to write docs, however my experience is that you
will end up turning everything into RST, therefore I would just add a
link to http://rst.ninjs.org/ or http://rst.aaroniles.net/ so that the
user can look on it.

However, I have doubts on the throughput of contributions there are.

>
> The wiki currently hosts and renders tables on the basis of data acquired
> and stored in a database.
> The table of packages and table of hardware. They are searchable and can be
> filtered.
> The table of hardware has a template system to let people add new devices to
> the "hardware database".
> https://lede-project.org/meta/create_new_dataentry_page
> Is there a way to do something like that with this new system?

We can setup a file to be copied and filled, and people would just
fill it. What is the objective of the database? What uses does it
have?

Anyway, if we did want to have something fed from a DB, we can always
create an extension that renders such thing. I have done similar work
to render different things, but I would try to avoid it.

Unless that database is linked somewhere, we could also create a
custom syntax in an extension to actually render in different ways all
the usages of such data (similar to how ToC, TODO lists, etc. work).

>
> Docuwiki allows people to translate the same pages to other languages, and
> keeps track of what pages have an out-of-sync translation.
> There are at least a couple asian translators
> (chinese/japanese/korean/whatever) and a russian guy that did some work
> there.

Sphinx supports gettext, so virtually everything could be translated.
If we integrated it with launchpad, transifex or zanata to name a few,
we would be able to have translations in any language, falling back to
english, and we would be able to have proper language coverage
statistics.

Also, because these places sometimes have translators roaming through
other opensource projects, we may end up getting better coverage.

> What exactly do you need? All wiki pages? Including history?
> Will look into this this evening. We will find an easy way.

Someone mentioned there were private pages, but if possible, I would
create a git repo, commit all the content and upload it to github. I
can work on a proper history rewrite if we want to keep history, but I
would just focus on the latest version, rewriting history later is
just git work.

Cheers,

-- 
Javier Domingo Cansino