I think a macro implies something that can be executed, and (rightly) ought to cause security-minded folks to double-take.
Conref isn't something we invented, it's straight out of DITA: http://dita.xml.org/arch-conref
708 karma · joined November 6, 2011
Conref isn't something we invented, it's straight out of DITA: http://dita.xml.org/arch-conref
Currently, yes, unfortunately. ;____; We've talked about doing it in an intermediate format, like YAML, which is slightly less painful, but....ugh. Years ago I wrote a very badly-coded-but-essentially-functional tool called Panino, which converted Markdown-to-JSON: https://github.com/gjtorikian/panino-docs/tree/master/lib/pa....
I see that some people have picked up on that and ran along with it, too: https://github.com/apiaryio/mson. So there might be something there to explore.
2. I've never looked into either. I know Swagger is used by several companies, like Twitter, but API Doc is new to me.
1. United States (average load: 1.97 s) 2. United Kingdom (average load: 2.29 s) 3. India (average load: 7.48 s) 4. China (average load: 12.11 s)
Average load of these countries is 6 seconds, which seems absolutely horrid...until I tell you that the US has about seven times more traffic than the UK.
I didn't want to fudge the graph and take out those slow outliers--the truth's the truth.
We're planning on splitting up the conref files by section. So for example, we'd get a separate conref file for Pages, one for UI stuff, one for Enterprise, etc. My only compliant with partials is that it's one piece of content per file, but it's a trade-off vs one file with several conrefs (gotta CTRL-F for that text you want to change).
I wish I could show up a sample, but I can't, because it's internal. ;)
Honestly, I think a lot of the engineering documentation started organically. When you have a small team working on a feature, it's difficult to scale explanations to the rest of the company. One day someone sits down and starts writing all their thoughts out in Markdown, and just checks it into a docs folder. That's it. It's easy-to-read, short on code, and usually full of ASCII, like this: https://i.imgur.com/KTbyhyq.png
Writing documentation is the best way to get outside contributors involved with minimal investment on your part. It also forces you to try and explain what you've built.
If you can't pretend to go back and look at things like a beginner, grab someone unfamiliar with the project, and have them describe to you what they would expect, and how they think they should proceed. They may be able to provide you with insights on what needs to be described.
1. The original documentation tool I wrote for Atom, Biscotto, kept track of the number of undocumented classes / methods: https://github.com/gjtorikian/biscotto/blob/59f48ba2621a92ae... . It was hooked up to CI, and if the count fell below a certain threshold, the test failed.
2. Right now, we're exploring into working with JSON schema as a means of providing both testing validation and accurate documentation. If the schema says "This REST method expects a parameter of this type," it becomes very easy to write a test to enforce that behavior; documentation can be easily generated from it; and of course your production code is safer for it.
I'm a huge fan of introducing more cross-overs between testing and documentation. I think a lot of time is spent on "clever" (and subjective) validations like http://www.hemingwayapp.com/, but not enough time is spent on basic content checks. It's very easy to drift code, tests, and docs apart. We need to start thinking about all three of them working together.
If it helps, I cherish this clip of Ron Paul and Ralph Nader discussing their similarities: https://www.youtube.com/watch?v=9J3-YoVPckk
That it's on CNN and Wolf Blitzer is just an inconsiderate ass is just the cherry on top to the larger point: you can have people from "different groups" that share some strong ideas. Personally I'd love it if both groups of people concentrated on their similarities over their differences to topple the status quo. After that we can quibble on the smaller issues. A single regime for a considerable length of time is rarely, if ever, a good idea.
Good news! There's a package for that: https://atom.io/packages/minimap
Have you hit the "t" key on the site?
I hope it will help you and other developers write better code.
As a former developer on Ace and now employee at GitHub I've honestly never run into a problem. I can't promise anything but I'd like to see what you mean.
As you might imagine, shoving in that many rows into the DOM kills any browser. G
The benefit of it being open-source was that I could try it, use it, and hack it, before deciding they'd done a damn good job.
I'd be really interested in hearing more about the problems you face, personally and within the firestation. If you'd like you can email me at my username [at] gmail.
A few Hubbers did see the site, but that is, of course, half the story, and I can honestly say that that wasn't the reason I got hired. I did also send in a resume weeks earlier, which did also get seen. It was the right place, the right time, and the right skills.
I would suspect--and this is just my opinion--that anyone attempting to create a site to highlight suggestions won't impress anyone. It worked once, and you'll need your own way to stand out. Uniqueness is what's valued here, not number of HN points or comments.
I'm going to mark my repo as Private to discourage copycats. I apologize for that.
The syntax highlighting rules for Ace were largely derived from tmlanguage files. This allows us to pretty easily import existing definitions. For example, Google had a tmlanguahe file for Dart that I was able to translate in less than an hour.
Could you describe more about what you like about CM's highlight rules? I admit I've never really looked into them. But I'm guessing by "show local variables in a different color" there's some parsing going on?