Documentation rework

[mapedraza]

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-rework branch 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)

[mapedraza]

Issues / PRs to have into account:

• Improve the Polling command documentation iotagent-ul#194 (comment)
• do not create initial entity #1390 (document when initial entity is created)

[mapedraza]

PRs that modify the doc after starting the rework:

• allow use static attributes from group in entityNameExp of group #1357
  • Done in dbd0498 (part of PR Additional changes to api.md file #1365)

[fgalan]

PR #1369 with the admin.md file

[mapedraza]

When merging PR #1371 the status should 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 remaining files are:

• architecture.md
• northboundinteractions.md
• deprecated.md
• getting-started.md
• index.md
• roadmap.md

For the fist 2, they can remain as independent document under devel folder (where they are right now).
deprecated.md, index.md and roadmap.md are also independent files, and they can remain as they are right now (just taking care of updating index.md links)
for getting-started.md, it can be renamed as user-guide, as it guides the IOTA users through the API, configurations, provision and measures sending.

[mapedraza]

After discussing with @fgalan and following the https://github.com/telefonicaid/fiware-orion documentation structure, the final document structure is the following:

Previous file	Current content	Current file
Contribution.md	Contribution guidelines	devel/development.md
advanced-topics.md	specific topics	api.md
api.md	API description	api.md
architecture.md	IoTA Architecture	devel/architecture.md
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	getting-started.md
howto.md	Uso de las funciones para implementar agente	devel/development.md
index.md		index.md
installationguide.md		admin.md
northboundinteractions.md		devel/northboundinteractions.md
operations.md	Alarms	admin.md
roadmap.md		roadmap.md
usermanual.md	JS functions descriptions (not real user manual, just developer manual)	devel/development.md