Change Details

Per discussions on IRC with @ajwillia.ms, the documentation should be built in order to support at least five languages: C, C++, JavaScript, Python, and C#. Building on Nate Drake's draft "Hello, World" C example documentation, I propose the creation of two or more additional draft "Hello, World" documents using alternative languages from the above list and featuring the bare minimum of changes (i.e. duplicate the existing C version, then go through and change whatever needs to be changed for it to be a Python version, the do the same for JavaScript.) Using these files we can then formulate and test an approach for the handling of language-specific documentation, from one of the following (or any other suggestion anyone has that could be better): * Separate each language out into its own namespace (the current approach, increases maintenance and risk of divergence); * Use a tabbed-code plugin to bring up only the user's required language (not portable, may not work for changes made outside code blocks); * Put no code in the documents themselves but have the code read in from external files (not portable, will not work for changes made outside code blocks); * Produce documentation in a single 'master' language then direct readers to appendices for alternative languages (unfriendly to those not using the 'master' language); * Produce 'master' documentation with all languages included then use an automated document generator to create language-specific documents in separate namespaces (reduces the maintenance and risk of divergence, but means the language-specific documentation will not be editable in DokuWiki as with the Eolian autodocs). The production of multi-language versions of Nate's "Hello, World" documentation will be vital in figuring out which of the above approaches to take - or an alternative approach not yet considered, suggestions for which are very much welcomed.

Per discussions on IRC with @ajwillia.ms, the documentation should be built in order to support at least five languages: C, C++, JavaScript, Python, and C#. Building on Nate Drake's draft "Hello, World" C example documentation, I propose the creation of two or more additional draft "Hello, World" documents using alternative languages from the above list and featuring the bare minimum of changes (i.e. duplicate the existing C version, then go through and change whatever needs to be changed for it to be a Python version, then do the same for JavaScript.) Using these files we can then formulate and test an approach for the handling of language-specific documentation, from one of the following (or any other suggestion anyone has that could be better): * Separate each language out into its own namespace (the current approach, increases maintenance and risk of divergence); * Use a tabbed-code plugin to bring up only the user's required language (not portable, may not work for changes made outside code blocks); * Put no code in the documents themselves but have the code read in from external files (not portable, will not work for changes made outside code blocks); * Produce documentation in a single 'master' language then direct readers to appendices for alternative languages (unfriendly to those not using the 'master' language); * Produce 'master' documentation with all languages included then use an automated document generator to create language-specific documents in separate namespaces (reduces the maintenance and risk of divergence, but means the language-specific documentation will not be editable in DokuWiki as with the Eolian autodocs). The production of multi-language versions of Nate's "Hello, World" documentation will be vital in figuring out which of the above approaches to take - or an alternative approach not yet considered, suggestions for which are very much welcomed.

Per discussions on IRC with @ajwillia.ms, the documentation should be built in order to support at least five languages: C, C++, JavaScript, Python, and C#. Building on Nate Drake's draft "Hello, World" C example documentation, I propose the creation of two or more additional draft "Hello, World" documents using alternative languages from the above list and featuring the bare minimum of changes (i.e. duplicate the existing C version, then go through and change whatever needs to be changed for it to be a Python version, then do the same for JavaScript.) Using these files we can then formulate and test an approach for the handling of language-specific documentation, from one of the following (or any other suggestion anyone has that could be better): * Separate each language out into its own namespace (the current approach, increases maintenance and risk of divergence); * Use a tabbed-code plugin to bring up only the user's required language (not portable, may not work for changes made outside code blocks); * Put no code in the documents themselves but have the code read in from external files (not portable, will not work for changes made outside code blocks); * Produce documentation in a single 'master' language then direct readers to appendices for alternative languages (unfriendly to those not using the 'master' language); * Produce 'master' documentation with all languages included then use an automated document generator to create language-specific documents in separate namespaces (reduces the maintenance and risk of divergence, but means the language-specific documentation will not be editable in DokuWiki as with the Eolian autodocs). The production of multi-language versions of Nate's "Hello, World" documentation will be vital in figuring out which of the above approaches to take - or an alternative approach not yet considered, suggestions for which are very much welcomed.