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,
signature.asc
Description: PGP signature
_______________________________________________ Lede-dev mailing list Lede-dev@lists.infradead.org http://lists.infradead.org/mailman/listinfo/lede-dev
