On 16/11/2017 21:42, Javier Domingo Cansino wrote:
Before this thread falls into oblivion, I would like to ask the guys
on charge of the docs (I think I got the correct emails) for feedback.
The general impression from the list that I have is that there are a
lot of doubts on if such a hardcore change in documentation will work,
but the benefits seem to be understood and good.
What if we kept the ToH + project related webpages as wikis, and we
just moved the guides and howtos to Sphinx based docs? Is this an
alternative you would prefer?
I really just want to improve the docs, so I would appreciate feedback
to either discard this proposal entirely or improve it until it's
accepted.
Cheers,
Javier
----
Below a summary of all the feedback:
* Alexander raised an idea about having docs and wiki together, I
don't see how we would separate that content, but I'm open to
suggestions.
* Sebastian raised his concerns about deterring casual contributions,
and I think after the text he agreed it's not as good, but is not that
bad neither
* Paul suggesting sticking to the wiki because it's easy to edit. If
possible I would like him to try the flow, as Sebastian did, to see
how more difficult he finds it.
* Alberto raised the concern on editing content by non-developers and
fixing links, however after Sebastian's tests I don't know his
opinion. Supposing of course that I create the appropriate tooling to
check doc correctness. He also suggested other GIT based wiki.
* Jow (for what I could understand) agreed in the idea of having more
control over the content, and that the lack of structure in Wikis make
difficult to find content.
My opinion on this: we are still talking about window dressing. What is
really needed is that some developer writes and keeps updated core and
developer documentation, whatever is best for developers to do that is
good for me.
Since they don't seem terribly interested in documentation in any form
(only Jow participated in this thread, and didn't say much beyond his
stylistic preferences and pointing out my mistake), I don't see the
point in changing the status quo.
It would just shuffle around the same text coming from the OpenWRT wiki
with minor updates done while it was in LEDE wiki while not changing the
main issue (and adding his own issues).
I mean OK, with git/readthedocs we would get a versioned documentation,
but it's not like there is a whole lot of text needing versioning
anyway, and it's easier to do like it was done in the OpenWRT wiki and
just state features available since version X or not available anymore
since version Y.
I'd like to see effort being put into actually creating new
documentation (reverse-engineering stuff or walking around the code) or
testing what there is (both on LEDE and OpenWRT).
That said, I'm ok with migrating all the wiki into Sphinx apart from
project pages and active content like ToH, table of packages and
device-specific pages (currently only in Openwrt wiki). But I'm still
just a volunteer maintainer, you'd probably need to talk with Ted Hess
for the wiki server access (to install Sphynx in it? I don't know how it
is set up exactly)
-Alberto
_______________________________________________
Lede-dev mailing list
Lede-dev@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/lede-dev
