[LEDE-DEV] Lede/Openwrt documentation

[Alberto Bursi]

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