ConDec enables to export decision knowledge and related knowledge elements, such as requirements, code, and work items. Three export formats are supported: Word, JSON, and Markdown. The user can filter the knowledge to be exported using the same filter criteria as in the knowledge graph views, e.g. by knowledge type, status, decision groups, and many other criteria.
The user can export knowledge either via the context menu in a knowledge graph view or via the More menu in the Jira issue view.
Context menu item to export the knowledge subgraph
Jira issue More menu item to export the knowledge subgraph
The user customizes the export e.g. by choosing the export format in the export dialog.
Dialog to export the knowledge subgraph offering the same filter criteria as in the views on the knowledge graph
Meeting managers can use the JSON export to create a meeting agenda using the ConDec Confluence plug-in.
The Java code for the knowledge export feature can be found here:
- Java REST API for export of list of knowledge elements used for Word and JSON export
- Java REST API for markdown export
The UI code for the knowledge export feature can be found here:
The knowledge elements listed below were exported via the knowledge export feature for the system function SF: Export knowledge from Jira, which specifies the export feature. In particular, the following filter criteria were used for the export:
- Selected element: system function SF: Export knowledge from Jira (CONDEC-484), which is a requirement for ConDec
- Link distance: 5 from the selected element
- Decision group: export
- Transitive links should be established. For example, the code file MarkdownCreator.java is only indirectly linked to the system function via a work item. The work item is not part of the export decision group, but the code file MarkdownCreator.java is part of this decision group. The code file is included in the filtered knowledge graph because of transitive linking. The code file contains decision knowledge documented in its code comments.
- All other filter criteria were the default filter criteria used in ConDec. For example, this means that the exported decision knowledge is taken from different documentation locations: entire Jira issues, Jira issue description and comments, commit messages, and code comments.
- SF: Export knowledge from Jira (CONDEC-484)
Which format do we support for exporting the knowledge documentation?
Use Word to export the decision knowledge documentation!
Word files can be edited.
PDF
PDF files cannot be edited.
- Use Markdown format to enable the export of the knowledge subgraph!
- Markdown text can be imported into github release notes and .md files for feature documentation.
- Is also used for release notes creation with explicit decision knowledge, thus, the code can be reused for general export.
- CSV
- Which word files should be supported?
- Word Docs should be supported, as it was well documented!
- How do we deal with irrelevant sentences/parts of text when exporting knowledge elements from Jira?
- The user is offered the same filter settings as in the knowledge graph views during export! Thus, the user can decide whether irrelevant text wrt. decision knowledge can be exported!
- Flexible solution because of same filtering possibilities in all views
- rejected: Irrelevant sentences are not included in the exported list of decision knowledge elements!
- How should disconnected sub-graphs be handled in the getElements REST API method?
- rejected: The knowledge-elements REST API method used to return a list of lists of elements belonging to a connected graph!
- This is hard to understand/low abstraction level.
- The knowledge-elements REST API method returns only one list of all elements matching the query!
- How to export and present decision knowledge from Jira into Confluence? (CONDEC-271)
- Create a Confluence plugin with a new macro to import decision knowledge from Jira into Confluence! (CONDEC-298)
- We add a possibility to export decision knowledge to the context menu! (CONDEC-480)
- Which machine readable format should be implemented?
- JSON should be used as machine readable format to export the knowledge documentation! (CONDEC-487)
- web standard, easily parsable, many libraries that can handle the JSON format
- CSV comma separated values
- hard to parse, not very flexible own parser has to be build, no data hierarchies
- Also readable by humans with excel, lightweight
- XML Extensive markup language
- Created for document markup, not for data exchange
- Full Data hierarchies, old standard for Documents
MarkdownCreator.java
- How can we include icon images into the markdown used for release notes and general knowledge export?
- We use the icon URL of github to include icon images into the markdown used for release notes and general knowledge export!
- The icons can be seen also by non Jira users. Thus, the markdown text could be excluded in external systems such as release page on github.
- We could use the icon URL on the Jira server.
- The icons could not be seen by non Jira users.
- How can we get the depth of an element in the markdown tree?
- We use the BreadthFirstIterator::getDepth method to get the depth of an element!
- We build the markdown with a DepthFirstIterator which does not offer a method getDepth. We currently traverse the graph twice: first, with a breadth first and second, with a depth first iterator, which is not very efficient.
- We could use a shortest path algorithm (e.g. Dijkstra) to determine the link distance.
- Might also not be very efficient.
- How to sort the exported knowledge elements?
- Sort elements by key when exporting them to Word and JSON!
- Keeps the order in Jira issue text
- Can be different to for example the order in the indented outline.
- We could change the REST API to return an ordered list created with e.g. a depth first iterator.
- Would take more computation effort
