Documentation For Your Apps


(Daniel Hollands) #21

I could be wrong, but the fact this is written in Python shouldn’t stop you being able to use it for Ruby (or any other) documentation.


(Marc Cooper) #22

It’s also available on via homebrew, which I consider a safe enough distance :slight_smile:

@woo is right in part. Markdown does allow separation of presentation, though I find it provides sufficient structure for most docs, though I might separate files (or similar in other tools).


(Andy Wootton) #23

@auxbuss’ post made the discovery below into a strange coincidence:

I’ve been interested in DocBook for years and I don’t remember ever seeing this document by Eric Raymond (The Cathedral & The Bazaar) before tonight
http://www.tldp.org/HOWTO/html_single/DocBook-Demystification-HOWTO/

I came here to share one of the links http://www.tldp.org/HOWTO/html_single/DocBook-Demystification-HOWTO/, and that section 2 suggests we’d all be happy if Markdown of small pieces of text could generate DocBook XML “from its back-end”. Sadly, I suspect that isn’t entirely possible because Markdown directly specifies presentation.

Section 3 makes a distinction between presentation markup and structural markup. I’m familiar with the concepts but I’m not sure I’d ever seen these phrases used together before to make the distinction so clear.

@stevejalim’s post fits my experience that Markdown is good enough to format a page but it’s easy to forget that books used to be made by sticking hand-written sheets together. That’s all you really need to make program documentation. Check your history books for “This page was intentionally left blank”.


(Andy Wootton) #24

Looks like I might be wrong about it not being possible to generate DocBook from Markdown, though I’ve seen people claim they can do it from MS Word and that requires magic, as far as I can see:

http://www.markdown2docbook.com/. Pandoc seems to have a go too.


(Steve Jalim) #25

Anyone still Sphinx? I hit the wall with that years ago, but it was powerful and good at the docstring-to-documenation thing


(Daveyon Mayne) #26

Not sure how to go about the installation for ruby, though.


(Daniel Hollands) #27

You wouldn’t. It’s a python app, it needs python. If you’re on a mac, it should be pre-installed, if not, it’s easy enough to install.


(Andy Wootton) #28

My mind has been thinking more rationally about this while I was asleep. A web site is a network. Structured markup is a tree to produce linear documents in a number of layouts. What we need as a generalised solution is a single source of content with a choice of alternate structures, to build different topologies from shared components. I should have known this because I’ve been thinking about the problem for months in relation to my own writing. It is a non-trivial problem. I think DITA may be a step in that direction.


(Andy Wootton) #29

While pursuing the idea that once inside emacs you can never leave, I’ve discovered emacs major Markdown-mode http://jblevins.org/projects/markdown-mode/ and minor mode https://www.emacswiki.org/emacs/MarkdownPreviewMode for web preview.


(Marc Cooper) #30

Structural markup => HTML. Presentation markup => CSS.

Similarly, markdown has structural markup, while presentation is independent; and might well be html & css.


(Andy Wootton) #31

When will I learn that my ‘obvious’ isn’t necessarily the same as someone else’s? (And we can both be right) Your interpretation of the phrases is perfectly valid, which sadly makes them useless for clarifying what I was trying to say and I don’t think it is what the author meant.

Section 3 that I linked to says, “Older formatting languages like Tex, Texinfo, and Troff supported presentation markup.” So do parts of LaTeX and HTML. It goes on to say, “In structural markup, you describe not the physical appearance of the document but the logical properties of its parts.” That’s DocBook (redefined in XML rather than SGML, birth parent of HTML, before it was temporarily fostered by XML) and DITA. I know! I’ve been FAR TOO interested in this problem for far too long.

HTML5 has tried to back off from earlier mistakes by adding new tags, so you can say ‘strong’ and ‘em’ for emphasis instead of ‘bold’ and ‘italics’. HTML’s original design brief was to make text look the same on different devices so it clearly needed presentation features. Unfortunately, it didn’t lose them when CSS was invented. HTML doesn’t ‘structural’ properly. If it says: ‘H1 text1 H2 text2’, any structural relationship between text2 and text1 has to be inferred from the heading styles.


(chrisc) #32

Totally missed this.

Our engineering handbook is GH pages. Our engineering block is statically generated by Wintersmith (loads of other gens are available) and when someone checks new content into master the build autodeploys the static site to an S3 bucket, from whence it is served.

Both are serverless solutions, which we like.

We were having a lot of trouble keeping docs in sync for our APIs. So new stuff is done via swagger, which is awesome as the same YAML file is the routing map within our app. Change the docs to update the app routes/params also. Documentation driven development. Yay!


(Stuart Langridge) #33

really? You’re using the swagger API docs as live code? That’s a neat trick which I had not thought of. Can you talk a bit more about that? For example, are you validating calls to API functions with the swagger docs of what the parameters should be?

(I know about using swagger to create test clients or test servers, but not to actually build the live service at runtime.)


(Andy Wootton) #34

Observation: traditional serial documentation and the network connections of a web site are different things. I think they have different use-cases. In the olden days, techie stuff often came with a ‘User Manual’ for relative newbies and a ‘Reference Manual’ for experienced people, to fill in gaps in their knowledge.

I’m struggling with this issue in my writing. I’ve been created a network of ‘conceptual objects’, often chunks of text that express an idea, in a language. I’m now struggling to find a book in there - hunting a viable story path or ‘plot’ through the wild wood I core-dumped out of my brain. I think this is ‘a collection’ of paths through a network with ideas presented in a way suitable for a particular target audience and with ‘knowledge dependencies’ met. I’m really sick of books with forward references that blow my stack. I could create more than one book from the same network of knowledge by travelling different paths, as many have.

This may make it clearer why I’m trying to write multiple books, keep in touch with latest Lean & Agile thinking and learn a Lisp ‘at the same time’, (which is impossible b.t.w. I have to interleave the activities.) I have a theory that you could allow people to wander Free in the forest but still sell them maps to a path, to save them time. I think this difference may be the interface between information and knowledge. It’s the policy the Forestry Commission sometimes follow on Cannock Chase, either by selling maps or indirectly, by having marked footpaths where there is paid car-parking.


(chrisc) #35

Yup that’s totally what we’re doing. Validates parameters and response models too. We can even weave our oAuth in with it. The documentation LITERALLY has to be complete and not out of date. Awesomeness.

Language support varies, and we’re not doing it everywhere yet, although that’s the aim. Most success with node.js using https://github.com/apigee-127/swagger-express.

We were discussing the other day doing a session on this at the next Codelicious, but thought it might be a snorefest for some.


(chrisc) #36

Here’s an example of the docs generated from the swagger yaml:

https://hierarchy.talis.com/docs/

And here’s the YAML:

https://hierarchy.talis.com/api-docs

In the YAML you can see x-swagger-router-controller extension which hooks up with an actual controller in express, operationId defines the method handler. Security is handled by the standard securityDefinitions swagger stuff and there is a hook at the top of our app to pass this though our own OAuth.

Our front controller is little thicker than normal setting all this up, but still only ~150 lines. And once it’s done new wiring is accomplished simply by extending the docs :slight_smile:


(Marc Cooper) #37

Wow! That’s some interesting stuff. Thank for posting it, @chrisc.

Nice job on the engineering handbook. I particularly like your charter. Those things have to be actionable, and you’ve nailed it.

I knew nothing of swagger <stands in corner> It looks interesting. I do like the idea of docs driving dev, because we’ve failed miserably to do it the other way around.

Promote shared, not individual code ownership

Man, almost every shop I go to I have to sort out this one. Tears. Always tears. :cry: