[LEDE-DEV] Lede/Openwrt documentation

[Ben Mulvihill]

May I make a late contribution to this thread?

As a user and occasional contributor to openwrt and lede I'd like to stress
how invaluable the openwrt wiki in its current form is, precisely because
it is real hotchpotch. Of course it is unstructured, of course there is
redundancy, of course some of it is out of date or plain wrong, but it is
still the first place I look when finding out about a new device, or
scratching my head trying to configure some new package.

I think two separate things are needed. FIrstly, as Alberto argues, core
documentation should be written, or at least reviewed, by developers, and
kept rigorously up-to-date. But there shouldn't be much of it, otherwise
keeping it up to date will involve too much work and simply won't happen.
Then secondly, the wiki should be allowed to continue in something like its
current anarchic form, to provide a space for device-specific information,
tutorials and howtos, projects using openwrt/lede etc. etc.

If it is necessary to migrate content, it would be great if the contents of
the current openwrt wiki could be preserved, maybe as a read-only "oldwiki".

On 17 November 2017 at 01:16, Alberto Bursi <bobafetthotmail at gmail.com> wrote:
>
>
> 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 at lists.infradead.org
> http://lists.infradead.org/mailman/listinfo/lede-dev