Description
This issue describes future task in order to improve the documentation of IoT Agents. After a initial analysis, the current files need to be reworked and merged into different files. The desired file structure, contining previous documentation is the following:
| Current file | Current content | Future file | Status |
|---|---|---|---|
| Contribution.md | Contribution guidelines | devel/development.md | ✅ |
| advanced-topics.md | specific topics | api.md | ✅ |
| api.md | API description | api.md | ✅ |
| architecture.md | IoTA Architecture | TBD | |
| deprecated.md | deprecations | deprecated.md | ✅ |
| development.md | How to run tests, contribute and coding styles | devel/development.md | ✅ |
| expressionLanguage.md | Information about expressions | api.md | ✅ |
| getting-started.md | Quick userguide | TBD | |
| howto.md | Uso de las funciones para implementar agente | devel/development.md | ✅ |
| index.md | index.md | ||
| installationguide.md | admin.md | ✅ | |
| northboundinteractions.md | TBD | ||
| operations.md | Alarms | admin.md | ✅ |
| roadmap.md | roadmap.md | ||
| usermanual.md | JS functions descriptions (not real user manual, just developer manual) | devel/development.md | ✅ |
The implementation plan is creating a branch (task/doc-rework) with all the documentation changes and merge by creating a PR containing all the changes. Previous smaller PR, one for each file (api.md, admin.md ...) should be opened against task/doc-rework to ease the review.
After reworking files, some tasks should be acomplished:
- Sync with master Sync
task/doc-reworkbranch with master #1436 - Review the whole documentation in order to remove deprecated / removed features. Things to check (non exhaustive list) Review the whole documentation in order to remove deprecated / removed features #1437:
- References to "plugin" (and its variant "plug-in")
- References to "bidirectional" (deprecated feature)
- References to "appendMode" and "IOTA_APPEND_MODE" (and its variants "append" and "APPEND") (deprecated feature)
- References to "legacy" and " expressionLanguage" (legacy expressions)
Deprecate: appendMode
- Decide and rename if necessary remaining files name and places Decide and rename if necessary remaining files name and places #1446
- Add readme.md under doc folder
- update index.md
- update RTD .yaml
Probably, at this point, merging task/doc-rework with master should be considered, since the rest of the takes could take much more time. Then:
At this point, iotagent-node-lib 3.4.0 has been released. The remainer tasks would be done in a next version
- Clean up index README.md, including doc ToC, and merge architecture and northbound documentations. #1470
- [Doc] Change the term services group to groups #1632
- [Doc] Modify getting started guide to use IoTA JSON #1645
- doc: lack of detail in Device datamodel #1409
- Corner cases provisioning
entityNameExp#1345 - [DOC] Add reusing context generated in expression to doc #1372
- Add binary data support doc (commands, measurements, specific paths, headers...)
- Final check to improve advanced features - specially related with JEXL features
- Add a list where expression are accepted (I.E: entityNameExpression, explicitAttrs, endpoint...)
- Include skipAttribute examples
- Include entityNameExpression
- Review warnings included due to potentialy outdated documentation:
- doc/devel/development.md#db-models (interesting)
- doc/devel/development.md#function-reference (hard)
- doc/devel/development.md#developing-a-new-iot-agent (hard)