Dynamic Documentation - Making documentation friendly & fun code : https://github.com/daniellawrence/ddoc

1. Dynamic Documentation
Making documentation friendly

2. & fun

3. $GREETINGS

4. G’DAY

5. {{NAME}}

6. Daniel

7. <<COMPANY>>

8. Linkedin

9. The problem

10. I
am
lazy

11. The lazy me
● things are hard

12. The lazy me
● things are hard
● once only once

13. The lazy me
● things are hard
● once only once
● copy and paste everything

14. I
am
lazy

15. I
am
lazy
and
forget
things

16. The forgetful me
● juggles too many things at once

17. The forgetful me
● juggles too many things at once
● systems are complex

18. The forgetful me
● juggles too many things at once
● systems are complex
● systems are not all the same

19. I
am
lazy
and
forget
things

20. The problem (cont.)

21. I run a project that
triggers all SRE and DEV
to make changes to their
systems.

22. Upgrading libs
Fixing up security issues
Monitoring coverage
Checking capacity
Latency
Etc. etc.

23. I want to make it as
easy
as possible
for everyone
to fix problems.

24. small
defined
problems
get fixed.

25. documentation
is the answer.

26. We have a page for
every type change
that is required.

27. Ideally we would have a
page for
every type for every
service.

28. However that would be
over 50,000 pages.

29. I know what you’re
thinking.

30. SHELL STYLE
$HOSTNAME
${NODENAME}

31. SHIFT STYLE
<<NODE-ID>>

32. TEST STYLE
[[FQDN]]

33. “double curly brace” STYLE
{IPv4}
{{IPv6}}

34. MUSTACHE STYLE
{IPv4}
{{IPv6}}

35. OTHER STYLE
(NODE)
((HOST))
{%IP%}

36. Too many styles
& I can’t copy and paste any* of them

37. SHELL STYLE (C&P)
HOSTNAME=$(hostname)
$HOSTNAME

38. We settled on {{mustache}} style.
1. It’s fun to say
2. it has some other advantages.

39. 39

40. 40

41. 41
It’s not too bad.. but

42. 42
Wouldn’t it be nice if we
had a templating engine?

43. 43
{{service_name}}
into
jobs-server

44. 44

45. 45

46. 46
AngularJS
image: CC BY 4.0 https://angular.io/presskit.html (2017)
Enter

47. 47
Our wiki
is missing
this feature

48. 48
Our wiki
was missing
this feature

49. 49
How ?

50. 50
querystrings

51. 51
http://wiki/page?service=jobs-server

52. 52
You can’t just add a <script> tag to
load javascript

53. 53
{html}
<script src=”https://cdn/angularjs.js”>
</script>
{html}

54. 54
Thanks {html} tag

55. 55
Back to looking at the query string
http://wiki/page?service=jobs-server

56. 56
var query = $location.search();
var service_name = query[‘service’];
$scope.service_name = service_name;
var url = ‘https://api/’ + service_name;
$http.get(url).success(
function(ctx) {
$scope.ctx = ctx;
}
);

57. 57
var query = $location.search();
var service_name = query[‘service’];
$scope.service_name = service_name;
var url = ‘https://api/’ + service_name;
$http.get(url).success(
function(ctx) {
$scope.ctx = ctx;
}
);

58. 58
var query = $location.search();
var service_name = query[‘service’];
$scope.service_name = service_name;
var url = ‘https://api/’ + service_name;
$http.get(url).success(
function(ctx) {
$scope.ctx = ctx;
}
);

59. 59
var query = $location.search();
var service_name = query[‘service’];
$scope.service_name = service_name;
var url = ‘https://api/’ + service_name;
$http.get(url).success(
function(ctx) {
$scope.ctx = ctx;
}
);

60. 60
That is all we need to use
{{service}}

61. 61
We are not stopping here.

62. 62
That project I talked about before.
also collections
A LOT
of interesting information

63. We can use that information

64. We just need to fetch it

65. 65
var query = $location.search();
var service_name = query[‘service’];
var url = ‘https://api/’ + service_name;
$http.get(url).success(
function(ctx) {
$scope.ctx = ctx;
}
);

66. 66
var query = $location.search();
var service_name = query[‘service’];
var url = ‘https://api/’ + service_name;
$http.get(url).success(
function(ctx) {
$scope.ctx = ctx;
}
);

67. 67
var query = $location.search();
var service_name = query[‘service’];
var url = ‘https://api/’ + service_name;
$http.get(url).success(
function(ctx) {
$scope.ctx = ctx;
}
);

68. 68
{{ctx.sre_group}}
becomes
jobs-team

69. 69
{{ctx.current_oncall}}
becomes
Daniel Lawrence

70. 70
{{ctx.ownership.owner_eng}}
{{ctx.number_of_hosts}}
{{ctx.product.lib.jetty.version}}
{{ctx.hosts.hostnames}}
{{ctx.is_deployed_in_prod}}
{{ctx.commits.last_commit}}

71. 71
AngularJS
image: CC BY 4.0 https://angular.io/presskit.html (2017)

72. show / hide data

73. 73

74. prompt for more info

76. Loops

77. <ul>
<li
ng-repeat="hostname in ctx.hosts">
{{hostname}}
</li>
</ul>

78. Figure out commands

80. /daniellawrence/ddoc
Where to go from here
images: https://about.gitlab.com/press/ & https://github.com/logos

81. Thanks
/daniellawrence/ddoc
images: https://about.gitlab.com/press/ & https://github.com/logos