> 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. 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, -- Javier Domingo Cansino _______________________________________________ Lede-dev mailing list Lede-dev@lists.infradead.org http://lists.infradead.org/mailman/listinfo/lede-dev
