[LEDE-DEV] Lede/Openwrt documentation

[Baptiste Jonglez]

Hi,

On 27-10-17, Javier Domingo Cansino wrote:
> > This problem is well-known [1,2] and can be solved by having access to a
> > common ancestor between the two versions.  A possible way to do this would
> > be to convert each wiki to a git repository [3], merge the two histories
> > using git, and then convert back the git repository to a dokuwiki
> > structure.  It sounds tedious but feasible.
> 
> As it looks like there are no clear decisions, I would like to propose
> the following changes.

To clarify: the "convert dokuwiki to git" thing I was talking about is
just a technical possibility for merging the OpenWrt wiki and the LEDE
wiki.  I was certainly not suggesting to switch to a completely new system
for the wiki: I think it's fine as it is for most of the documentation.

> Git backed documentation:
>  * It's easier to have all the content at a glance sorted in folders
> to help structure the documentation
>  * You can move content between pages easier
> 
> Use github as a place to host the document repository:
>  * There are buildhooks from services integrated, such as github pages
> or readthedocs that make it transparent to collaborate
>  * Users can provide feedback through issues on missing docs, giving
> tips to contributors to see what areas can be improved
>  * Discussions about documental structure happen openly, easing burden
> on people maintaining documentation by having an specific pipe
> everything goes through
>  * Contributions can be reviewed or automatically contributed if diff
> < 100 lines (I can do a simple bot for that)
> 
> Integrate existing openwrt docs inside lede structure.
>  * Having an structured documentation helps user know where to look
> for the content
>  * Makes easier to spot a place to write your contribution at
>  * It is more user / dev-newbie friendly
> 
> Switch to sphinx
>  * Most of the times there is no clue on where to place the
> documentation, so you create a new wiki page, this leads to duplicate
> information
>  * Can generate HTML Single page, pdf, epub, etc. Although the usual
> one is the multipage HTML
>  * Can be hosted in readthedocs and integrated with github so that
> every deployment is automatic
>  * Can tag versions, so in the event we finally reach a good
> documentation, users can browse different docs for each version
>  * It's industry standard for project documentation. Not only about
> documenting python
>  * It has good to go skins that are proven to be easy to read
>  * More complete syntax (if something like that would be required
> 
> Drawbacks I see:
>  * Contributions in the wiki are instant, here they would have a
> proper process to review.
>  * There is a migration effort to be done, greater than just merging
> docs in the same place
> 
> I volunteer however to setup today an example with the current lede
> docs in sphinx, so that you can see the look and feel I am speaking
> about.
> 
> Also, openwrt.readthedocs.org is taken but if we were to make official
> this proposal, I would contact the current owner or rtd people to get
> it transferred.
> 
> Cheers,
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <http://lists.infradead.org/pipermail/lede-dev/attachments/20171027/516b58ad/attachment.sig>