Hi there! I started playing around with improving the Mercurial docs but before I work on it more and send some patches, I wanted to get some opinions about what people would like to see here. Sorry about the length of this email but there's a lot to do IMHO.
What I have in mind is the following grand plan (I don't know if I'll get to do everything but this is what I would _like_ to happen): 1. Make doc/Makefile also generate one html and man page per command and extension. - This would let us see the doc for, say, `hg status` over at https://www.mercurial-scm.org/doc/hg-status.1.html - When you just want to check the docs for a single command, it's a lot easier than having to search "status" (with multiple hits) on the giant hg.1.html page (I know I could just check the doc in my terminal but sometimes I can't, or I prefer the browser for one reason or another) - It would generate `hg-<cmd>.1` pages (note the .1 suffix) because we have this 1:1 mapping between man pages and html pages -- I assume we want to keep that. - This would also give us the ability to type, say, `man hg-status` and get a man-formatted version of `hg help status`. I don't care too much for that but I suppose it doesn't hurt. 2. Improve integration of generated docs inside the website - Change the html template used to generate the html docs so that it has the standard website navigation around the content. - Right now that's the top horizontal menu, more or less (but that might change, see next points). - If people prefer the online docs to not have this, we could generate 2 versions of the html: the `<whatever>.1.html` would be the "naked" man- like doc in html form, while the `<whatever>.html` (without the man- like number suffix) would be the "website integrated form"... or maybe not and we just force people to hit the Back button often. - Generate some doc index page with links to all the other generated pages (categorized links to each command page, general links to hgignore/hgrc, extensions, etc.) 3. Improve the website itself - Adding some proper link to the reference documentation (i.e. the generated html doc pages... note how my previous point mentions generating an index page for those, so that's what we would link to) - Take a hard look at the navigation. Right now we have only a top horizontal menu, which means only a handful of menu items at most. This means that a lot of the navigation should be done with clear lists of subpages on each top level page, so that it's easy to get a mental picture of the website's structure, but in practice the links are placed organically in the text and I find that confusing. It's especially confusing when you have somewhat duplicate things (a "Quickstart" sidebar on the main page, but also a dedicated "quickstart" page), links to take you out to the wiki, interesting pages whose links are buried in the text ("learn" page), etc. - There should be a "Release Notes" or "What's New" link on the website (I couldn't find one?), shown prominently on the "Downloads" page, and that should link to a "proper" website page, too (possibly generated like the reference docs), instead of linking to the wiki (but that depends on how much manual labour goes into publishing the release notes, I'm not familiar with that process). - Similarly, I think the "Extensions" page on the website should be a "proper" website page, at least as far as general docs and bundled extensions go. It could link to the wiki for 3rd party extensions. Honestly, it could (should?) be a link to the `hg help extensions` topic as generated in html form, with some added bells and whistles like links to each extension's reference doc page. - Add some "Get Involved" page (couldn't find any either?) for how to ask for help, report bugs, and contribute patches. 4. Make reference docs versioned - The reference docs (hg.1.html, hg-status.1.html, hgignore.5.html, etc.) should be versioned, so you can check out the docs from a prior version of Mercurial (which is particularly helpful when helping someone). Phew, I think that's it! Right now, I've got #1 mostly figured out and done, and I started playing around with #2. Comments? -- l u d o . . 8 0 17 80 _______________________________________________ Mercurial-devel mailing list Mercurial-devel@mercurial-scm.org https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel
