 |
 |
On May 9, 2014, at 09:12, Kian-Tat Lim <[log in to unmask]> wrote: >> >> How we machine generate full docs is something that that we (== System Architect?) need to deal with (e.g. use sphinx?), and I'm not sure that confluence is the answer. The answer, "It's all in doxygen" is probably not correct either. > > We == SAT. But I think we need some evaluation of the alternatives. Serendipitously, Josh and I attended the Write The Docs conference on software documentation last week. Let me give a quick summary in case it is of interest in this context, since the conference centered around programmer-to-programmer documentation (such as APIs) and project-to-technical-user documentation (such as Python docs). For the dot-com folks that provide Software-As-A-Service, API documentation is often their most valuable business acquisition tool (“We used X because they had a well-documented API”) so there is a lot of serious thinking going on in this area. I would summarise the predominant opinions as: - Wikis are generally bad. They lack ability to maintain structure, and they are “away from the code” - easy to forget to keep up to date. The only people who made wikis work seemed to be the projects where there was a full time person associated with contributing material to them, and endlessly haranguing developers to keep them updated. - Automatically generated documentation from code (cf java) is bad. It feeds the delusion that “we have documentation” when in fact the documentation of highest value is tutorials and overview descriptions such as those that you often find in READMEs, as well as thinking that often occurs in the context of commit logs and code comments. - The model used by the people who seemed happiest with their solution involved schemes like plain-text (typically Markdwown) documentation in git repos, pulled together (eg. as submodules in a Docs repo), and then turned into a website through a static page generator (of which Jekyll was one example) by the “docs person”. The arguments for the last solution (git + markdown + static generator) seemed to be: - Developers already have a workflow based on git. Getting them to work outside that flow is problematic, so why not work with it rather than against it. - You are far more likely to fix documentation when it is in the same checkout as the code you just fixed. - In the case of recalcitrant developers who won’t use Markdown or your template, it’s not a big deal to fix it up for them. - Static page generators separate content from presentation completely, and so are ideal to ensure mobile-device compatibility and other accessibility requirements at one central point. It turns out a large percentage of people out there consult documentation on mobile devices. - If you use git, you can do release management for documentation same as your code - eg. have the “v3” version of the website in a branch, and when the code release for “v3” happens, you cut over to it right away so it matches. - You can use github (or whatever your repo management solution is) to leverage other tools (such as the Issue Tracker) to open tickets against people for incomplete documentation. - Docs/UI/UX people can give developers a git repo with documentation templates to clone, so as to propagate important parts of your documentation standard (eg. a LICENCE section) - Putting docs in the code tree allows you to harness your software process to ensure documentation really happens. For example you can require for people to “Make docs” as well as “Make test” before their pull request is accepted to master, or have a documentation check be part of the code review process. - Git is more powerful and flexible than any CMS you can think of, so why not use it. - git+static code generators give you flexibility to support localisation efforts in other languages quite easily. The git-based badnwagon was so strong that one talk was essentially a (to be honest not very good) git primer for the people there who came from the tech writer background rather than the developer background. I will also say that some people also advocated “README Driven Development” where you have to write the README before the code (by analogy to TDD). I’m still mulling that over. We kept copious notes so we can give a longer rundown if anyone is still interested after the above. Mario will be delighted to know that Josh gave the Atlassian guy (polite) hell over their seemingly deliberate disdain for Markdown. PS. I will say by far the funniest moment was the Google Cloud guy complaining that Amazon’s cloud service docs were easily googlable whereas Google’s were not. PPS. And for anybody with spare time and interest, Brian Troutwine gave a lovely talk on understanding complex systems through monitoring: http://videos.writethedocs.org/video/64/instrumentation-as-living-documentation-teaching — Frossie [log in to unmask] ######################################################################## Use REPLY-ALL to reply to list To unsubscribe from the QSERV-L list, click the following link: https://listserv.slac.stanford.edu/cgi-bin/wa?SUBED1=QSERV-L&A=1