## Document as Code powen.tan@tcstock --- ## Agenda - What is Document as Code - Benefit of Docs as Code - My Point of View - Markdown - Draw Chart - Plantuml v.s. Mermaid - HackMD - Takeaway --- ## What is Document as Code Writing docs with the same tools as code: - Issue Trackers - Version Control (Git) - Plain Text Markup (Markdown) - Code Reviews - Automated Tests --- ## Benefit of Docs as Code Writers integrate better with development teams - Writers integrate better with development teams - Developers will often write a first draft of documentation - No merge code branch without Docs --- ## My Point of View ==What is Docs Code== > Use text with markup language to generate document and control it by a versioning system. --- ==Benefit of Docs as Code== - More productivity (editing without distracted UI) Fitts's law: $MT = a+b\cdot ID=a + b \cdot \log_2\frac{2D}{W}$  - Versioning (v.s. version control) - Compare changes between version --- ## Markdown ### Heading 3 ```text ### Heading 3 ``` > Quote ```text > Quote ``` 1. number1 2. number2 ```text 1. number1 2. number2 ``` --- *italitc* **bold** ==yellow== ```text *italitc* **bold** ==yellow== ``` - list1 - list2 ```text - list1 - list2 ``` - [ ] checklist1 - [ ] checklist2 ```text - [ ] checklist1 - [ ] checklist2 ``` --- | Diagram | Plantuml | Mermaid | | -----------| -------- | --------| | Sequence | O | O | | Class | O | O | | Use Case | O | X | ```text | Diagram | Plantuml | Mermaid | | -----------| -------- | --------| | Sequence | O | O | | Class | O | O | | Use Case | O | X | ``` --- ### Hackmd special :::success success ::: ``` :::success success ::: ``` :::info info ::: :::warning warning ::: :::danger danger ::: --- ### Emoji :-1: :+1: :100: :1234: :accept: ```text :-1: :+1: :100: :1234: :accept: ``` --- ### Code and Math Formula ```python print('Hello World') ``` $$MT = a + b \cdot\log_2\frac{2D}{W}$$ ```text $$MT = a + b \cdot\log_2\frac{2D}{W}$$ ``` --- ### Draw Chart Use markup language to generate charts/diagram Markup Language - Plantuml - Mermaid --- ## Plantuml v.s. Mermaid | Diagram | Plantuml | Mermaid | | ------------------------------ | -------- | ------------------------- | | Sequence | O | O (No box group) | | Class | O | O | | Use Case | O | X | | Activity | O | X (Flowchart) | | Component | O | X (Flowchart) | | State | O | O | | Object | O | | --- | Diagram | Plantuml | Mermaid | | ------------------------------ | -------- | ------------------------- | | Deployment | O | | | Timing | O | | | Network | O | | | Wireframe | O | | | Archimate | O | | | Gantt | O | O | | MindMap | O | (Markmap) | | WBS (Work Breakdown Structure) | O | | --- | Diagram | Plantuml | Mermaid | | ------------------------------ | -------- | ------------------------- | | JSON/YMAL | O | | | Pie Chart | X | O | | User Jorney | X | O | --- ## Plantuml v.s. Mermaid - Plantuml - Pro: - Support many diagrams and use cases - Con: - Syntax is not compact --- ## Plantuml v.s. Mermaid (cont.) - Mermaid - Pro: - Native JavaScript library - Customize interaction in the chart - Con: - Less diagram/feature supports - Lack of consistence in diagram syntax - Community developemnt is slow: - [sequence diagram request: grouping actors in box](https://github.com/mermaid-js/mermaid/issues/1505) --- ## HackMD  --- ## Demo - [HackMD Features](https://hackmd.io/features?both) - [Create Real Life AWS Diagrams](https://crashedmind.github.io/PlantUMLHitchhikersGuide/aws/aws.html) - [Markdown to Mind Map](https://hackmd.io/4eWJb7VZQz2PBj3Z4tdrUg) - [API Sequence Diagram](https://hackmd.io/YaqGv297QHeQ6a0UtF3OjA) - [Gantt chart](https://hackmd.io/mDpd0GyERwaZ2QAp2GqTYg) --- ## Takeaway - Document: - Markdown - Draw Chart: - Plantuml - rich diagrams and features - Mermaid: - interaction - web native --- | Diagram | Suggested Tool | | -------- | -------- | | Sequence | plantuml | | Component| mermaid | | State | plantuml| | Mindmap | markmap | | Gantt | plantuml(easy to write)<br>mermaid(easy to maintatin)| --- ## Questions --- ## References - [Docs as Code](https://www.writethedocs.org/guide/docs-as-code/) - [HackMD](https://www.writethedocs.org/guide/docs-as-code/)