Hi All I'm the technical writer who will be doing the "work". I have many years of general experience in writing for tools and programming languages, and also at working with communities to create documentation (you can find out a little about me here: http://www.linkedin.com/in/hamishwillee ). I'm used to working collaboratively, and I would REALLY appreciate your help to make this project successful.
Thanks very much for all the suggestions and questions - I'll be reviewing them and including anything relevant in the plan. Below are some specific responses. If I've missed yours, then please repost or contact me directly on hamishwillee at gmail dot com. Please re-split out appropriate sections if you believe they require further discussion. --------------- @msc >What do you see as the advantages of Jekyll vs. a wiki? Over the Github Wiki? #HW The main goal of this project is to create a more professional documentation set, which will be used in both an improved website and in the SDK. The wiki is not suitable for this purpose. The wiki is a great platform for community development, and we'll be mining the existing material as a base for the new documents. If people want to contribute specific topics to the documentation set then creating them on wiki first is a really good idea. One reason I like jekyll is that it uses a near-compatible version of markdown syntax for the content (exactly the same as the wiki). Not only will this make porting the existing content trivial, but you will still be able to edit the content and preview it in almost exactly the same way as you do currently (of course the final output will look a little different as we'll be using different stylesheets). Note also that the wiki will not be going away - though I will be removing duplicate material. > Will we have to learn YAML (yet another markup language)? >It seems there may be something called YAML. I do not mean that language in particular. #HW No (or only a trivial amount) Jekyll parses markdown files which start with "front matter". This is almost exactly the same for each topic and is human readable. If editing an existing topic you would ignore this part of the file. If creating a new topic you will copy-paste from an existing topic and just update one or two files.. I will also be creating a "contributor" guide for whatever solution is selected. --------------- @ Bruce Mitchener > I really like working with Sphinx and ReStructured Text: http://sphinx-doc.org/ > I've used it (successfully) to produce thousands of pages of technical documentation, encompassing multiple books. We publish these materials in HTML, PDF and ePub. We've written our own extensions as needed and it has been pretty easy. #HW Thanks very much. I have not used Sphinx but I will review it and respond properly. My uninformed 10 second view is that Markdown/wiki text is easier to learn and use than ReStructured text. There is also a real "ease of use" benefit of markdown on Github because it can be previewed by the author (on the site) without them having to learn the Jekyll toolchain. The ability to publish to PDF or ePub is great - but is not IMO a key selection criteria. --------------- @ Warren Seine > If you like Sphinx, you should definitely have a look at ReadTheDocs. Basically, it's a platform for hosting documentation from Sphinx source files. The source of the documentation stays on GitHub and documentation is regenerated on commit hooks. It's quite popular in the Python community, though there's nothing specific to the language. #HW Thanks, I will check this out too. --------------- @Trevor Linton > I'd be happy to help. One aspect I think could use a very thorough once over is the emscripten.h C documentation, shouldn't be difficult bringing it to a wiki or jekyll. Also, the emcc/em++ command line options, there are some options aren't documented (other than the paragraph found in the help). #HW This is very much in line with my thinking - as documenting this sort of thing is one way to work out the omissions in the higher level guide material. I also hope to create/source more complete documentation on the test code - and as part of that either separate out or better identify the code which works well as "example code" In terms of the documentation in header files and tools, my experience is that it is best that documentation remains "in source" and is extracted using tools. > If there's anything you'd like me to take a pass at, let me know. #HW Thank you. I certainly will! I don't yet know the established "ways of working" but I assume if you see a defect in docs you can create an issue and either assign or request that it be assigned to me. If you already know of specific omissions and are happy to contribute a proposed solution/text then please do. It does not have to be "perfect" as I will subedit. --------------- @Alon > I guess the first question here is where to put the docs - we have emscripten.h docs inline, and I'm worried about copying it to another place without removing the original, to avoid duplication and one being out of date etc. So the question is, is comments in the source better than a separate doc? Comes down to what people prefer I guess. Thoughts? #HW My experience is that developers like documentation everywhere, but that as an author it makes sense to only have one master copy. The usual solution is to have in-source and extract using tools. Doxygen is a common solution to this problem, but depends on the format of the comments. --------------- @Trevor Linton > I'm not sure, it's unfortunately one of those problems i'm unsure if there's a complete solution to. The documentation is very complete in emscripten.h, i'm generally a fan of looking at things from users perspectives. Most who are looking at documentation or have questions would first go to the documentation (at least that's my experience), generally someone pokes around at a header file as a last resort (at least thats just me). In addition, jekyll and wiki's have the luxury of layout which allows you to add images, diagrams, links to other sources. So, i'd say simple notes in the header that refer to the URL for the documentation and keep all the documentation in one place. #HW See previous comment. My concern about links is that URLs change. I like comments in source, because it encourages developers to update the documentation when the code changes. --------------- @msc >>On 21/06/2014 05:35, Trevor Linton wrote: >>I'm not sure, it's unfortunately one of those problems i'm unsure if there's a complete solution to. The documentation is very complete in emscripten.h, i'm generally a fan of looking at things from users perspectives. Most who are looking at documentation or have questions would first go to the documentation (at least that's my experience), generally someone pokes around at a header file as a last resort (at least thats just me). In addition, jekyll and wiki's have the luxury of layout which allows you to add images, diagrams, links to other sources. So, i'd say simple notes in the header that refer to the URL for the documentation and keep all the documentation in one place. >The solution to this problem is tools like Doxygen. Such tools allow you to write the documentation in the .h file in a way from which the tool can generate more user friendly documentation. I think it is a good idea to have the full documentation with the code because it is more likely to get updated when the code is updated. Tools like Doxygen enable this. Regards #HW Yes. To be very pedantic "the full documentation of the code in the code". There will be documentation that is not in the code. Doxygen is a good tool, but does require specific syntax for comments. #HW Note also, that we will want to make sure that the command line tool documentation also remains in-sync without our docs. --------------- @Alon Zakai > We want to be able to write modern-looking docs that can be viewed online, as well as shipped together with an SDK in offline form (for a specific version). A third place we might want them is if we some day write a dedicated emscripten website, then the docs should be easily transferable to another online site. Github pages seems limited for the second and third use cases here, AFAICT. #HW The output of Jekyll is a static site which can be hosted anywhere. The limitation is that as it is static you can't run server side code (for example a database for logins or whatever). It is perfectly suitable for both the current proposed site on Github pages and the SDK (where you can't run server-side scripts anyway). Whether it is suitable for the "third case" depends the requirements of such a site. At that point if you needed the docs you could migrate them to the new system or just use Jekyll (or whatever) to to build them and then dump the raw HTML. The minor limitation with Jekyll that I'll have to workaround is that we'll need separate entry points for the SDK and the site - so will need to export the SDK entry point somewhere during build. --------------- @Trevor Linton I should add, having somewhere that has all of the -s compiling flags would be helpful, I had to dig into the actual emcc python script to get an understanding of some of them. #HW I will add this to "the list" --------------- @Warren Seine > Regarding the documentation content, here's what I would suggest: refactor the Technical Documentation into a User Guide remove any specific page from the main page (like "EGL support in Emscripten" or "Running html files with emrun") turn each subpage into an action (like "Compiling", "Binding", "Embedding", "Running", "Debugging", "Packaging", "Publishing") in a "Publishing", explain how to properly embed an Emscripten application (right now, I'm sure everybody copy/paste the generated HTML and hack it) make first time access easier make sure the Tutorial is the first thing people go through (I think it's good and should be highlighted even more) move all screencasts, blog posts (official and unofficial), tutorials and slides out of the User Guide move any "Issues" subsection into one Troubleshooting page with complete error messages (so it can be indexed and searched) introduce the core team in a single place (with Twitter and GitHub handles, blogs) clean up the demo list separate demos from tools / engines / libraries (it's somehow confusing right now) update the demo list with direct link to the code (if available) and the actual demo format it as a table ("name", "description", "author", "submission date", "demo link", "source code") I know it's a big list. What do you think? #HW Yes :-) All of the above is very much in line with my current thinking and my understanding of best-practise. I will need some help for some of the clean-up. We should also identify those lists which really need to remain in wiki. >make a gist to build from source (I've made one but it's somehow broken) instead of listing steps for Linux (and remove any old confusing third-party links) #HW This is something I need to review to better understand. >detail the project status #HW I'm thinking of a release notes section - or are you thinking of "roadmap"? > turn the roadmap into a Trello board Great minds :-) http://hamishwillee.github.io/2014/06/20/Trello-project-management-tools-and-burndown-charts/ I had already started one "for myself" - from which I was planning delivering a snapshot :-) If people want to email me their email details (hamishwillee at gmail dot com) I'm happy to share it. --------------- @msc >"First thing, is this running after main() finished? See NO_EXIT_RUNTIME in src/settings.js regarding that." One of the problems I would like the documentation revamp to solve is the need to provide references like the above. We want to be able to provide a URL that when clicked takes you straight to the relevant document (and even section) rather than being told to look at the source. See my earlier message about doxygen-like tools for a way to accomplish this and have the full documentation in the source, without duplication. I think we should make a list of the problems to be solved before choosing technology. #HW Agreed. > I suspect the demo list should stay on the current wiki, and not be part of the documentation revamp. Yes, we certainly need to keep it up to date and add links to code etc. as you suggest. Table format would be good also. If you or anyone else wants to do that, that would be great. #HW I will need to review this because I don't know enough yet to evaluate. Generally speaking it that makes sense to have "official" demos and examples in the documentation set, or at least linked from it. By official I mean "known to be impressive, and to work with current versions of the tool". Maintaining a less official list on wiki is a good idea. #HW I can make the list a table, but will hold off until discussion complete. > -- You received this message because you are subscribed to the Google Groups "emscripten-discuss" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. For more options, visit https://groups.google.com/d/optout.
